<!DOCTYPE html>
<html>
<head>
<title>RDFa DOM API 1.1</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<!-- 
  === NOTA BENE ===
  For the three scripts below, if your spec resides on dev.w3 you can check them
  out in the same tree and use relative links so that they'll work offline,
  -->
<script type="text/javascript"
  src="http://dev.w3.org/2009/dap/ReSpec.js/js/respec.js" class="remove">
 </script>
<script type="text/javascript" class="remove">

    var preProc = {
          apply:  function(c) {
                    // extend the bibliography entries
                    berjon.biblio["HTML-RDFA"] = "Manu Sporny; et al. <a href=\"http://www.w3.org/TR/rdfa-in-html/\"><cite>HTML+RDFa</cite></a> 04 March 2010. W3C Working Draft. URL: <a href=\"http://www.w3.org/TR/rdfa-in-html/\">http://www.w3.org/TR/rdfa-in-html/</a> ";
                    berjon.biblio["BCP47"] = "A. Phillips, M. Davis. <a href=\"http://tools.ietf.org/rfc/bcp/bcp47.txt\"><cite>Tags for Identifying Languages</cite></a> September 2009. IETF Best Current Practice. URL: <a href=\"http://tools.ietf.org/rfc/bcp/bcp47.txt\">http://tools.ietf.org/rfc/bcp/bcp47.txt</a>";
                    
                    // process the document before anything else is done
                    var refs = document.querySelectorAll('adef') ;
                    for (var i = 0; i < refs.length; i++) {
                        var item = refs[i];
                        var p = item.parentNode ;
                        var con = item.innerHTML ;
                        var sp = document.createElement( 'dfn' ) ;
                        var tit = item.getAttribute('title') ;
                        if (!tit) {
                            tit = con;
                        }
                        sp.className = 'adef' ;
                        sp.title=tit ;
                        sp.innerHTML = con ;
                        p.replaceChild(sp, item) ;
                    }
                    refs = document.querySelectorAll('aref') ;
                    for (var i = 0; i < refs.length; i++) {
                        var item = refs[i];
                        var p = item.parentNode ;
                        var con = item.innerHTML ;
                        var sp = document.createElement( 'a' ) ;
                        sp.className = 'aref' ;
                        sp.setAttribute('title', con);
                        sp.innerHTML = '@'+con ;
                        p.replaceChild(sp, item) ;
                    }
                    // local datatype references
                    refs = document.querySelectorAll('ldtref') ;
                    for (var i = 0; i < refs.length; i++) {
                        var item = refs[i];
                        if (!item) continue ;
                        var p = item.parentNode ;
                        var con = item.innerHTML ;
                        var ref = item.getAttribute('title') ;
                        if (!ref) {
                            ref = item.textContent ;
                        }
                        if (ref) {
                            ref = ref.replace(/\n/g, '_') ;
                            ref = ref.replace(/\s+/g, '_') ;
                        }
                        var sp = document.createElement( 'a' ) ;
                        sp.className = 'datatype';
                        sp.title = ref ;
                        sp.innerHTML = con ;
                        p.replaceChild(sp, item) ;
                    }
                    // external datatype references
                    refs = document.querySelectorAll('dtref') ;
                    for (var i = 0; i < refs.length; i++) {
                        var item = refs[i];
                        if (!item) continue ;
                        var p = item.parentNode ;
                        var con = item.innerHTML ;
                        var ref = item.getAttribute('title') ;
                        if (!ref) {
                            ref = item.textContent ;
                        }
                        if (ref) {
                            ref = ref.replace(/\n/g, '_') ;
                            ref = ref.replace(/\s+/g, '_') ;
                        }
                        var sp = document.createElement( 'a' ) ;
                        sp.className = 'externalDFN';
                        sp.title = ref ;
                        sp.innerHTML = con ;
                        p.replaceChild(sp, item) ;
                    }
                    // now do terms
                    refs = document.querySelectorAll('tdef') ;
                    for (var i = 0; i < refs.length; i++) {
                        var item = refs[i];
                        if (!item) continue ;
                        var p = item.parentNode ;
                        var con = item.innerHTML ;
                        var ref = item.getAttribute('title') ;
                        if (!ref) {
                            ref = item.textContent ;
                        }
                        if (ref) {
                            ref = ref.replace(/\n/g, '_') ;
                            ref = ref.replace(/\s+/g, '_') ;
                        }
                        var sp = document.createElement( 'dfn' ) ;
                        sp.title = ref ;
                        sp.innerHTML = con ;
                        p.replaceChild(sp, item) ;
                    }
                    // now term references
                    refs = document.querySelectorAll('tref') ;
                    for (var i = 0; i < refs.length; i++) {
                        var item = refs[i];
                        if (!item) continue ;
                        var p = item.parentNode ;
                        var con = item.innerHTML ;
                        var ref = item.getAttribute('title') ;
                        if (!ref) {
                            ref = item.textContent ;
                        }
                        if (ref) {
                            ref = ref.replace(/\n/g, '_') ;
                            ref = ref.replace(/\s+/g, '_') ;
                        }

                        var sp = document.createElement( 'a' ) ;
                        var id = item.textContent ;
                        sp.className = 'tref' ;
                        sp.title = ref ;
                        sp.innerHTML = con ;
                        p.replaceChild(sp, item) ;
                    }
                }
        } ;


      var respecConfig = {
          // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
          specStatus:           "FPWD",
          //publishDate:          "2010-04-29",
          // copyrightStart:       "2010",
          
          // the specification's short name, as in http://www.w3.org/TR/short-name/
          shortName:            "rdfa-dom-api",
          subtitle:             "An API for extracting structured data from Web documents",
          // if you wish the publication date to be other than today, set this
          // publishDate:  "2009-08-06",

          // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
          // and its maturity status
          // previousPublishDate:  "1977-03-15",
          // previousMaturity:  "WD",

          // if there a publicly available Editor's Draft, this is the link
          edDraftURI:           "http://www.w3.org/2010/02/rdfa/sources/rdfa-dom-api/",

          // if this is a LCWD, uncomment and set the end of its review period
          // lcEnd: "2009-08-05",

          // if you want to have extra CSS, append them to this list
          // it is recommended that the respec.css stylesheet be kept
          extraCSS:             ["http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],

          // editors, add as many as you like
          // only "name" is required
          editors:  [
              { name: "Benjamin Adrian", url: "http://www.dfki.uni-kl.de/~adrian/",
                company: "German Research Center for Artificial Intelligence GmbH", companyURL: "http://www.dfki.de/" },
              { name: "Manu Sporny", url: "http://digitalbazaar.com/",
                company: "Digital Bazaar, Inc.", companyURL: "http://digitalbazaar.com/" },
              { name: "Mark Birbeck", url: "http://webbackplane.com/",
                company: "Backplane Ltd.", companyURL: "http://webbackplane.com/" },
          ],

          // authors, add as many as you like. 
          // This is optional, uncomment if you have authors as well as editors.
          // only "name" is required. Same format as editors.

          //authors:  [
          //    { name: "Your Name", url: "http://example.org/",
          //      company: "Your Company", companyURL: "http://example.com/" },
          //],
          
          // name of the WG
          wg:           "RDFa Working Group",
          
          // URI of the public WG page
          wgURI:        "http://www.w3.org/2010/02/rdfa/",
          
          // name (with the @w3c.org) of the public mailing to which comments are due
          wgPublicList: "public-rdfa-wg",
          
          // URI of the patent status for this WG, for Rec-track documents
          // !!!! IMPORTANT !!!!
          // This is important for Rec-track documents, do not copy a patent URI from a random
          // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
          // Team Contact.
          wgPatentURI:  "http://www.w3.org/Consortium/Patent-Policy-20040205/",
          maxTocLevel: 3,
          preProcess: [ preProc ] 
      };

      function updateExample(doc, content) {
        // perform transformations to make it render and prettier
        content = content.replace(/<!--/, '');
        content = content.replace(/-->/, '');
        content = doc._esc(content);
        content = content.replace(/\*\*\*\*([^*]*)\*\*\*\*/g, '<span class="hilite">$1</span>') ;
        return content ;
      }

      function updateDTD(doc, content) {
        // perform transformations to
        // make it render and prettier
        content = '<pre class="dtd">' + doc._esc(content) + '</pre>';
        content = content.replace(/!ENTITY % ([^ \t\r\n]*)/g, '!ENTITY <span class="entity">% $1</span>');
        content = content.replace(/!ELEMENT ([^ \t$]*)/mg, '!ELEMENT <span class="element">$1</span>');
        return content;
      }

      function updateSchema(doc, content) {
        // perform transformations to
        // make it render and prettier
        content = '<pre class="dtd">' + doc._esc(content) + '</pre>';
        content = content.replace(/&lt;xs:element\s+name=&quot;([^&]*)&quot;/g, '&lt;xs:element name="<span class="element" id="schema_element_$1">$1</span>"') ;
        return content;
      }

      function updateTTL(doc, content) {
        // perform transformations to
        // make it render and prettier
        content = '<pre class="sh_sourceCode">' + doc._esc(content) + '</pre>';
        content = content.replace(/@prefix/g, '<span class="sh_keyword">@prefix</span>');
        return content;
      }
  </script>
</head>

<body>
<section id="abstract">
<p>
RDFa [[!RDFA-CORE]] enables authors to publish structured information that is both 
human- and machine-readable. Concepts that have traditionally been
difficult for machines to detect, like people, places, events, music, movies, 
and recipes, are now easily marked up in Web documents. While publishing this
data is vital to the growth of 
<a href="http://en.wikipedia.org/wiki/Linked_data">Linked Data</a>, 
using the information to improve the collective utility of the Web for humankind 
is the true goal. 
To accomplish this goal, it must be simple for Web developers to extract and 
utilize structured information from a Web document. This document details such a 
mechanism; an RDFa Document Object Model Application Programming Interface 
(RDFa DOM API) that allows simple extraction and usage of structured 
information from a Web document.
</p>

<section class="informative">
<h3>How to Read this Document</h3>

<p>
This document is a detailed specification for an <em>RDFa
DOM API</em>. The document is primarily intended for the following audiences:
</p>
<ul>
  <li>User Agent developers that are providing a mechanism to programatically
  extract RDF Triples from RDFa in a host language such as XHTML+RDFa 
  [[XHTML-RDFA]], HTML+RDFa [[HTML-RDFA]] or SVG Tiny 1.2 [[SVGTINY12]],
  </li>
  <li>DOM tool developers that want to provide a mechanism for extracting
  RDFa content via programming languages such as JavaScript, Python, Ruby,
  or Perl, and </li>
  <li>Developers that want to understand the inner workings and design
  criteria for the RDFa DOM API.</li>
</ul>

<p>
For those looking for an introduction to the use of RDFa, or some
real-world examples, please consult the RDFa Primer [[RDFA-PRIMER]].</p>

<p>
If you are not familiar with RDF, you should read about the
Resource Description Framework (RDF) [[RDF-CONCEPTS]] before reading this
document. The [[RDF-CONCEPTS]] document outlines the core data model that 
is used by RDFa to express information.</p>
  
<p>
If you are not familiar with RDFa, you should read and understand the
[[!RDFA-CORE]] specification. It describes how data is encoded in host
languages using RDFa. A solid understanding of concepts in RDFa Core will 
inevitably help you understand how the RDFa DOM API works in concert
with how the data is expressed in a host language.
</p>

<p>
If you are a Web developer and are already familiar with RDF and RDFa, and 
you want to programatically extract RDFa content from documents, then you will 
find the <a href="#the-rdfa-api">RDFa API</a> section of most interest. 
It contains a handful of JavaScript examples on how to use the 
<em>RDFa DOM API</em>.</p>

<p>
Readers who are not familiar with the Terse RDF Triple Language [[TURTLE]] 
may want to read the specification in order to understand the
short-hand RDF notation used in some of the examples.</p>
  
<p>
This document uses the <em>Web Interface Definition Language</em> 
[[WEBIDL]] to specify all language bindings. If you intend to implement
the <em>RDFa DOM API</em> you should be familiar with the Web IDL language
[[WEBIDL]].</p>

<p>
Examples may contain references to existing vocabularies and use
abbreviations in CURIEs and source code. The following is a list of all
vocabularies and their abbreviations, as used in this document:
</p>

<ul>
  <li>The <a href="http://www.w3.org/1999/02/22-rdf-syntax-ns#">RDF</a>
  vocabulary (abbreviation: <code>rdf</code>, e.g., <code>rdf:type</code>)</li>
  <li>The <a href="http://www.w3.org/2001/XMLSchema#">XSD</a>
  vocabulary (abbreviation: <code>xsd</code>, e.g., <code>xsd:integer</code>)</li>
  <li>The <a href="http://www.w3.org/2000/01/rdf-schema#">RDF
  schema</a> vocabulary (abbreviation: <code>rdfs</code>, e.g., <code>rdfs:label</code>)</li>
  <li>The <a href="http://xmlns.com/foaf/spec/">Friend-Of-A-Friend</a>
  vocabulary (abbreviation: <code>foaf</code>, e.g., <code>foaf:name</code>)</li>
</ul>

</section>
</section>

<section id='sotd'>
<!-- <p>
This document has been reviewed by W3C Members, by software
developers, and by other W3C groups and interested parties, and is
endorsed by the Director as a W3C Recommendation. It is a stable
document and may be used as reference material or cited from another
document. W3C's role in making the Recommendation is to draw attention
to the specification and to promote its widespread deployment. This
enhances the functionality and interoperability of the Web.
</p> -->
</section>
<!-- END SOTD -->

<section class='informative'>

<h1>Introduction</h1>

<p>
RDFa provides a means to attach properties to elements in XML and HTML 
documents. Since the purpose of these additional properties is to provide 
information about real-world items, such as people, films, companies, events, 
and so on, properties are grouped into objects called Property Groups.
</p>

<p>
The RDFa DOM API provides a set of interfaces that make it easy to manipulate DOM 
objects that contain information that is also part of a Property Group. This 
specification defines these interfaces.
</p>

<p>
A document that contains RDFa effectively provides two data layers. The first 
layer is the information about the document itself, such as the relationship 
between the elements, the value of its attributes, the origin of the document, 
and so on, and this information is usually provided by the Document Object 
Model, or DOM [[DOM-LEVEL-1]].
</p>

<p>
The second data layer comprises information provided by embedded metadata, such 
as company names, film titles, ratings, and so on, and this is usually provided 
by RDFa [[RDFA-CORE]], Microformats [[MICROFORMATS]], DC-HTML, GRDDL,
or Microdata.
</p>

<p>
Whilst this embedded information could be accessed via the usual DOM interfaces
-- for example, by iterating through child elements and checking attribute 
values -- the potentially complex interrelationships between the data mean 
that it is more efficient for developers if they have access to the data after 
it has been interpreted.
</p>

<p>
For example, a document may contain the name of a person in one section and the
phone number of the same person in another; whilst the basic DOM interfaces 
provide access to these two pieces of information through normal navigation, it 
is more convenient for authors to have these two pieces of information 
available in one property collection, reflecting the final Property Group.
</p>

<p>
All of this is achieved through the RDFa DOM API.
</p>

<p>
There are many scenarios in which the RDFa DOM API can be used to extract
information from a Web document. The following sections describe a few of
these scenarios.
</p>

<section>
<h3>Importing Data</h3>
<p>
Amy has enriched her band's web-site to include Google Rich Snippets event 
information. Google Rich Snippets are used to mark up information for the 
search engine to use when displaying enhanced search results. Amy also uses some 
JavaScript code that she found on the web that automatically extracts the event 
information from a page and adds an entry into a personal calendar.
</p>
<p>
Brian finds Amy's web-site through Google and opens the band's page. He decides 
that he wants to go to the next concert. Brian is able to add the details to 
his calendar by clicking on the link that is automatically generated by the
Javascript tool. The Javascript extracts the RDFa from the web page and places
the event into Brian's personal calendaring software - Google Calendar.
</p>

<pre class="example" data-transform='updateExample'><!--
<div prefix="v: http://rdf.data-vocabulary.org/#" typeof="v:Event"> 
  <a rel="v:url" href="http://amyandtheredfoxies.example.com/events" 
     property="v:summary">Tour Info: Amy And The Red Foxies</a>
  
  <span rel="v:location">
  	<a typeof="v:Organization" rel="v:url" href="http://www.kammgarn.de/" property="v:name">Kammgarn</a>
  </span>
  <div rel="v:photo"><img src="foxies.jpg"/></div>
  <span property="v:description">Hey K-Town, Amy And The Red Foxies will rock Kammgarn in October.</span>
  When: 
  <span property="v:startDate" content="2009-10-15T19:00">15. Oct., 7:00 pm</span>-
  <span property="v:endDate" content="2009-10-15T21:00">9:00 pm</span>
  </span>

  Category: <span property="v:eventType">concert</span>
</div>
--></pre>

</section>
<section>
<h3>Enhanced Browser Interfaces</h3>
<p>
Dave is writing a browser plugin that filters product offers in a web page and
displays an icon to buy the product or save it to a public wishlist. The
plugin searches for any mention of product names, thumbnails, and offered 
prices. The information is listed in the URL bar as an icon, and upon clicking
the icon, displayed in a sidebar in the browser. He can then add each item to
a list that is managed by the browser plugin and published on a wishlist 
website.
</p>
<pre class="example" data-transform='updateExample'>
<!-- 
<div prefix="rdfs: http://www.w3.org/2000/01/rdf-schema#
             foaf: http://xmlns.com/foaf/0.1/
             gr: http://purl.org/goodrelations/v1# 
             xsd: http://www.w3.org/2001/XMLSchema#">
 
  <div about="#offering" typeof="gr:Offering">
    <div property="rdfs:label" content="Harry Potter and the Deathly Hallows" xml:lang="en"></div>
    <div property="rdfs:comment" content="In this final, seventh installment of the Harry Potter series, J.K. Rowling 
    unveils in spectactular fashion the answers to the many questions that have been so eagerly 
    awaited. The spellbinding, richly woven narrative, which plunges, twists and turns at a 
    breathtaking pace, confirms the author as a mistress of storytelling, whose books will be read, 
    reread and read again." xml:lang="en"></div>
    <div rel="foaf:depiction" resource="http://ecx.images-amazon.com/images/I/51ynI7I-qnL._SL500_AA300_.jpg"></div>
    <div rel="gr:hasBusinessFunction" resource="http://purl.org/goodrelations/v1#Sell"></div>
    <div rel="gr:hasPriceSpecification">
      <div typeof="gr:UnitPriceSpecification">
        <div property="gr:hasCurrency" content="USD" datatype="xsd:string"></div>
        <div property="gr:hasCurrencyValue" content="7.49" datatype="xsd:float"></div>
      </div>
    </div>
    <div rel="gr:acceptedPaymentMethods" resource="http://purl.org/goodrelations/v1#PayPal"></div>
    <div rel="gr:acceptedPaymentMethods" resource="http://purl.org/goodrelations/v1#MasterCard"></div>
    <div rel="foaf:page" resource="http://www.amazon.com/Harry-Potter-Deathly-Hallows-Book/dp/0545139708"></div>
  </div>
   
   
</div>
-->
</pre>

</section>
<section>
<h3>Data-based Web Page Modification</h3>
<p>
Dale has a site that contains a number of images, showcasing his photography. 
He has already used RDFa to add licensing information about the images to his 
pages, following the instructions provided by Creative Commons. Dale would 
like to display the correct Creative Commons icons for each image so that people
will be able to quickly determine which licenses apply to each image.
</p>

<pre class="example" data-transform='updateExample' >
<!-- 
<div prefix="cc: http://creativecommons.org/ns#">
  <img src="http://dale.example.com/images/image1.png" 
       rel="cc:license" 
       resource="http://creativecommons.org/licenses/by/3.0/us/"/>
<a 
   href="http://dale.example.com" property="cc:attributionName" 
   rel="cc:attributionURL">Dale</a>
</div>   
 -->
</pre>

</section>
<section>
<h3>Automatic Summaries</h3>
<p>
Mary is responsible for keeping the projects section of her company's home page
up-to-date. She wants to display info-boxes that summarize details about the
members associated with each project. The information should appear when
hovering the mouse over the link to each member's homepage. Since each
member's homepage is annotated with RDFa, Mary writes a script that requests 
the page's content and extracts necessary information via the RDFa DOM API.
</p>
<pre class="example" data-transform='updateExample'>
<!-- 
<div prefix="dc: http://purl.org/dc/terms/ foaf: http://xmlns.com/foaf/0.1/" >
<span about="#me" property="foaf:name" content="Bob">My<span> interests are:
<ol about="#me" typeof="foaf:Person">
<li rel="foaf:interests"><a href="facebook" rel="tag" property="dc:title">facebook</a></li>
<li rel="foaf:interests"><a href="opengraph" rel="tag" property="dc:title">opengraph</a></li>
<li rel="foaf:interests"><a href="semanticweb" rel="tag" property="dc:title">semanticweb</a></li>
</ol>
<p>
Please follow me on 
<span about="#me" rel="foaf:account">
<a href="http://twitter.com/bob" typeof="foaf:term_OnlineAccount" property="foaf:accountName">http://twitter.com/bob</a>.
</p>
</div>
-->
</pre>

</section>
<section>
<h3>Data Visualization</h3>
<p>
Richard has created a site that lists his favourite restaurants and their
locations. He doesn't want to generate code specific to the various mapping 
services on the Web. Instead of creating specific markup for Yahoo Maps, 
Google Maps, MapQuest, and Google Earth, he instead adds address information 
via RDFa to each restaurant entry. This enables him to build on top of the 
structured data in the page as well as letting visitors to the site use the
same data to create innovative new applications based on the address information
in the page.
</p>

<pre class="example" data-transform='updateExample'>
<!-- 
	<div prefix="vc: http://www.w3.org/2006/vcard/ns# foaf: http://xmlns.com/foaf/0.1/" typeof="vc:VCard">
		<span property="vc:fn">Wong Kei</span>
		<span property="vc:street-address">41-43 Wardour Street</span>
		<span>
			<span property="vc:locality">London</span>, <span property="vc:country-name">United Kingdom</span>
		</span>
		<span property="vc:tel">020 74373071</span>
	</div>
-->
</pre>

</section>
<section>
<h3>Linked Data Mashups</h3>
<p>
Marie is a chemist, researching the effects of ethanol on the spatial 
orientation of animals. She writes about her research on her blog and often 
makes references to chemical compounds. She would like any reference to these 
compounds to automatically have a picture of the compound's structure shown 
as a tooltip, and a link to the compound's entry on the National Center for 
Biotechnology Information [NCBI] Web site. Similarly, she would like visitors
to be able to visualize the chemical compound in the page using a new HTML5
canvas widget she has found on the web that combines data from different 
chemistry websites.
</p>

<pre class="example" data-transform='updateExample'>
<!--
<div prefix="dbp: http://dbpedia.org/ontology/ fb: http://rdf.freebase.com/rdf/" >
   My latest study about the effects of 
   <span about="[fb:en.ethanol]" 
      typeof="[dbp:ChemicalCompound]" 
      property="[fb:chemistry.chemical_compound.pubchem_id]" 
      content="702">ethanol</span> on mice's spatial orientation show that ...
</div>
-->
</pre>
<!-- http://pubchem.ncbi.nlm.nih.gov/summary/summary.cgi?cid=702 -->

</section>

</section>

<section class='informative'>
<h1>Design Considerations</h1>

<p>
RDFa 1.0 [[RDFA-SYNTAX]] has seen substantial growth since it became
an official W3C Recommendation in October 2008. It has seen wide
adoption among search companies, e-commerce sites, governments, and
content management systems. There are numerous interoperable
implementations and growth is expected to continue to rise with the
latest releases of RDFa 1.1 [[!RDFA-CORE]], XHTML+RDFa 1.1 [[!XHTML-RDFA]],
and HTML+RDFa 1.1 [[!HTML-RDFA]].</p>

<p>
In an effort to ensure that Web applications are able
to fully utilize RDFa, this specification outlines an API and a set of
interfaces that extract RDF Triples from Web documents or other document formats
that utilize RDFa. The <em>RDFa DOM API</em> is designed with maximum
code expressiveness and ease of use in mind. Furthermore, a deep understanding 
of RDF and RDFa is not necessary in order to extract and utilize the 
structured data embedded in RDFa documents.</p>

<p>
Since there are many Web browsers and programming environments for the Web,
the rapid adoption of RDFa requires an interoperable
API that Web document designers can count on being available in all Web 
browsers. The <em>RDFa DOM API</em> provides a uniform and developer-friendly 
interface for extracting RDFa from Web documents.</p>

<p>
Since most browser-based applications and browser extensions that
utilize Web documents are written in JavaScript [[ECMA-262]], the 
implementation of the <em>RDFa DOM API</em> is primarily concerned with 
ensuring that concepts covered in this document are easily utilized 
in JavaScript.
</p>

<p>
While JavaScript is of primary concern, the <em>RDFa DOM API</em>
specification is language independent and is designed such that DOM tool
developers may implement it in many of the other common Web programming 
languages such as Python, Java, Perl, and Ruby. Objects that are defined by the 
RDFA DOM API are designed to work as seamlessly as possible with language-native
types, operators, and program flow constructs.
</p>

<section>
<h3>Goals</h3>

<p>The design goals that drove the creation of the APIs that are described in 
this document are:</p>

<dl>
<dt>Ease of Use and Expressiveness</dt>
<dd>
While this should be a design goal for all APIs, special care is taken to
ensure that developers can accomplish common tasks using a minimal amount of
code. While execution speed is always an important factor to consider, it is
secondary to minimizing the amount of work a developer must perform to 
extract and use data contained in the document.
</dd>
<dt>Modularity and Pluggability</dt>
<dd>
Each part of the API is modular and pluggable, meaning that data storage, 
parsers and query modules may be replaced by other developer-defined mechanisms
as long as the interfaces listed in this document are supported.
</dd>
<dt>DOM Orthogonality</dt>
<dd>
Interfaces defined on the Document should match programming
paradigms that are familiar to developers. For example, if one were to 
attempt to retrieve Element Nodes by Subject, the name of the method should
be <code>document.getElementsBySubject()</code>, which mirrors the
<code>document.getElementsById()</code> functionality that is a part of
[[DOM-LEVEL-1]].
</dd>
<dt>Support for Non-RDFa Parsers</dt>
<dd>
Other languages that store data in the DOM are considered as first-class 
languages when it comes to extraction and support via the RDFa DOM API.
Mechanisms like DC-HTML, eRDF, Microformats, and Microdata can be used to
express structured data in DOM-based languages. It is a goal of this DOM API 
to ensure that information expressed in these languages can be extracted, 
using a developer-defined parser, and stored in the Data Store.
</dd>
<dt>Low-level Access and the Freedom to Tinker</dt>
<dd>
Providing an abstract API, while simpler, may not produce the
kind of innovation that the semantics community would like to see. It is 
important to give developers access to the entire RDFa DOM API stack in order 
to ensure that each layer of the stack can be improved independently of 
a standards body.
</dd>
<dt>Native Language Constructs</dt>
<dd>
Data is exposed and processed in a way that is natural for Javascript and
many other Web programming languages like Python, Ruby and even C++. For 
example, Property Groups can be exposed as native objects or dynamically
accessible, associative arrays. Data Stores can be iterated over by providing
an anonymous function or function pointer. By ensuring that programming language
constructs are considered in the design of the API, we ensure that the API
won't fight the language and thus, the developer.
</dd>
<dt>Macros and Templates</dt>
<dd>Some of the mechanisms that underpin RDF are difficult to use in everyday
programming. For example, having to type out an entire URI is not only 
laborious for a programmer, but also error prone and overly-verbose. RDFa
Core [[RDFA-CORE]] introduces the concept of a Compact URI Expression, or
CURIE. This API builds on the CURIE concept and allows IRIs to be expressed 
as CURIEs. The API should also provide short-cuts that reduce the amount of
code that has to be repeated. Property Group Templates are one example of
reducing repetitive code writing as it can be stored in a single variable
and re-used for objects.</dd>
</dl>
</section>

<section>
<h3>Concept Diagram</h3>

<p>
The following diagram describes the relationship between all concepts discussed
in this document. 
</p>

<!-- 
It's 2010, WHY DOESN'T SVG JUST WORK!!! ~~ manu
<object data="concept-stack.svg" type="image/svg+xml" width="100%" height="53%">
   <img src="concept-stack.png" alt="The RDFa DOM API Concept Stack" />
</object>
-->
<!-- GAAAARRRRH! COME ON! ~~ manu
<div data-include="concept-stack.svg"></div>
-->

<div style="margin: 0 auto; text-align: center;" >
   <img style="width: 50%;" src="concept-stack.png" alt="The RDFa DOM API Concept Stack" />
<p><strong>Diagram of RDFa DOM API Concepts</strong></p>
</div>

<p>
The lowest layer of the API defines the basic structures that are used to store
information; IRI, Plain Literal, Typed Literal, Blank Node and finally the 
RDF Triple.
</p>

<p>
The next layer of the API, the Data Store, supports the storage of information.
</p>

<p>
The Data Parser and Data Query interfaces directly interact with the Data Store. 
The Data Parser is used to extract information from the Document and store the
result in a Data Store. The Data Query interface is used to extract different
views of data from the Data Store. The Property Group is an abstract, 
easily manipulable view of this information for developers. While
Property Group objects can address most use cases, a developer
also has access to the information in the Data Store at a basic level. Access to 
the raw data allows developers to create new views and ways of directly
manipulating the data in a Data Store.
</p>

<p>
The highest layer to the API is the Document object and is what most
web developers will use to retrieve Property Groups created from data stored
in the document.
</p>
</section>

</section>

<section class='informative'>
<h1>Developing with the API</h1>


<section class='informative'>

<h2>Basic Concepts</h2>

<p>
This API provides a number of interfaces to enable:
</p>

<ul>
<li>parsing of DOM objects that contain embedded
metadata;</li>
<li>extraction of the embedded metadata into a data store;</li>
<li>querying a data store in order to retrieve Property Groups from the data store.
</li>
</ul>

<section>
<h3>The Basic API</h3>

<p>
The RDFa DOM API has a number of advanced methods that can be used to
access the Data Store, Data Parser and Data Query mechanisms. Most web 
developers will not need to use the advanced methods - most will only require
the following interfaces for most of their day-to-day development activities.
</p>

<h4>Retrieving Property Groups</h4>

 <dl>
   <dt><code>document.getItemsByType(type)</code></dt>
   <dd>Retrieves a list of Property Groups by their type, 
       such as <code>foaf:Person</code>.</dd> 
   <dt><code>document.getItemBySubject(type)</code></dt>
   <dd>Retrieves a single Property Group by its subject, 
       such as <code>http://example.org/people#bob</code>.</dd> 
   <dt><code>document.getItemsByProperty(property, optional value)</code></dt>
   <dd>Retrieves a list of Property Groups by a particular property and optional
       value that the Property Group contains.</dd>
 </dl>

<h4>Retrieving DOM Elements</h4>

 <dl>
   <dt><code>document.getElementsByType(type)</code></dt>
   <dd>Retrieves a list of DOM Nodes by the type of data that they express, 
       such as <code>foaf:Person</code>.</dd> 
   <dt><code>document.getElementsBySubject(type)</code></dt>
   <dd>Retrieves a list of DOM Nodes by the subject associated with the
       data that they express, 
       such as <code>http://example.org/people#bob</code>.</dd>
   <dt><code>document.getElementsByProperty(property, optional value)</code></dt>
   <dd>Retrieves a list of DOM Nodes by a particular property and optional
       value that each expresses.</dd>
 </dl>
 
<h4>IRI Mapping</h4>
 
 <dl>
   <dt><code>document.data.context.setMapping(prefix, iri)</code></dt>
   <dd>Gets and sets short-hand IRI mappings that are used by the API, such as
      expanding <code>foaf:Person</code> to 
      <code>http://xmlns.com/foaf/0.1/Person</code>.</dd>
 </dl>

<h4>Advanced Processing</h4>

 <dl>
   <dt><code>document.data.query.select(query, template)</code></dt> 
   <dd>Retrieves an array of Property Groups based on a set of selection criteria.</dd>
   <dt><code>document.data.store.filter(subject, predicate, object)</code></dt>
   <dd>Filters a given Data Store by matching a given triple pattern.</dd>
   <dt><code>document.data.parser.iterate(iterFunction)</code></dt>
   <dd>Iterates through a DOM, passing every data item to the iteration
       function that is passed into the method.</dd>
 </dl>

</section>

<section>
<h3>Using the Basic API</h3>

<p>
The following section uses the markup shown below to demonstrate how to extract
and use Property Groups using the RDFa DOM API. The following markup is assumed to
be served from a document located at <code>http://example.org/people</code>.
</p>

<pre class="example">
&lt;div prefix="foaf: http://xmlns.com/foaf/0.1/" about="#albert" typeof="foaf:Person"&gt;
  &lt;span property="foaf:name"&gt;Albert Einstein&lt;/span&gt;
&lt;/div&gt;
</pre>



<section>
<h3>Working with Property Groups</h3>

<h4>Retrieving Property Groups by Type</h4>

<p>You can retrieve the object that is described above by doing the following:
</p>

<pre class="example">
var people = document.getItemsByType("http://xmlns.com/foaf/0.1/Person");
</pre>

or you can specify a short-cut to use when specifying the IRI:

<pre class="example">
document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/");
var people = document.getItemsByType("foaf:Person");
</pre>

<h4>Retrieving Property Groups by Subject</h4>

<p>You can also get a Property Group by its subject:</p>

<pre class="example">
var albert = document.getItemBySubject("http://example.org/people#albert");
</pre>

<p>You can also specify a relative IRI and the document IRI will be 
automatically pre-pended:</p>

<pre class="example">
var albert = document.getItemBySubject("#albert");
</pre>

<h4>Retrieving Property Groups by Property</h4>

<p>You can get a list of Property Groups by their properties:</p>

<pre class="example">
var peopleNamedAlbertEinstein = document.getItemByProperty("foaf:name", "Albert Einstein");
</pre>

<h4>Using Property Groups</h4>

<p>
You can retrieve property values from Property Groups like so:
</p>

<pre class="example">
var albert = document.getItemBySubject("#albert");
var name = albert.get("foaf:name");
</pre>

<p>You can also specify values that you would like to map to Property Group
attributes:</p>

<pre class="example">
var albert = document.getItemBySubject("#albert", {"foaf:name": "name"});
var name = albert.name;
</pre>

</section>

<section>
<h3>Managing Elements with Data</h3>

<h4>Retrieving Elements Containing Data by Type</h4>

<p>You can retrieve the DOM Node that is described above by doing the following:
</p>

<pre class="example">
var elements = document.getElementsByType("http://xmlns.com/foaf/0.1/Person");
</pre>

or you can specify a short-cut to use when specifying the IRI:

<pre class="example">
document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/");
var elements = document.getElementsByType("foaf:Person");
</pre>

<h4>Retrieving Elements Containing Data by Subject</h4>

<p>You can also get a list of Elements by the subject of data:</p>

<pre class="example">
var elements = document.getElementsBySubject("http://example.org/people#albert");
</pre>

<p>You can also specify a relative IRI and the document IRI will be 
automatically pre-pended:</p>

<pre class="example">
var elements = document.getElementsBySubject("#albert");
</pre>

<h4>Retrieving Elements by Property</h4>

<p>You can get a list of Elements by the properties and values that
they declare:</p>

<pre class="example">
var elements = document.getElementsByProperty("foaf:name", "Albert Einstein");
</pre>

<h4>Modifying DOM Elements</h4>

<p>
You can modify elements that are returned just like any other DOM Node, 
for example:
</p>

<pre class="example">
<!--
var elements = document.getElementsByProperty("foaf:name", "Bob");
for(i = 0; i <= elements.length; i++)
{
   var e = elements[i];
   e.style.setProperty('color', '#00cc00', null);
}
-->
</pre>

<p>
The code above would change the color of all the areas of the page where the
item's name is "Bob" to green.
</p>

</section>
</section>

</section>

<section>
<h2>Advanced Concepts</h2>

<p>
This section covers a number of concepts that go beyond basic everyday usage of
the RDFa DOM API. The interfaces to the DOM API allow you to work with data
at an abstract level, or query structured data and override key parts of the
software stack in order to extend the functionality that the API provides.
</p>

<section>
<h3>Advanced Queries</h3>

<p>
The features available via a Query object will depend on the
implementation. However, all conforming processors will provide the
basic element selection mechanisms described here.
</p>

<section>
<h4>Querying by Type</h4>

<p>
Perhaps the most basic task is to select Property Groups of a
particular type. The type of a Property Group is set in RDFa via
the special attribute <code>@typeof</code>. For example, the following
markup expresses a Property Group of type <i>Person</i> in the
Friend-of-a-Friend vocabulary:
</p>

<pre class="example">
&lt;div typeof="foaf:Person"&gt;
  &lt;span property="foaf:name"&gt;Albert Einstein&lt;/span&gt;
&lt;/div&gt;
</pre>

<p>
To locate all Property Groups that are people we would do the
following:</p>

<pre class="example">
var query = document.data.createQuery("rdfa", store);
var ar = query.select( { "rdf:type": "foaf:Person" } );
</pre>

<p>
Note that the Query object has access to the mappings provided via
the document.data.context object, so they can also be used in queries. It is 
also possible to write the same query in a way that is independent of
any prefix-mappings:</p>

<pre class="example">
var ar = query.select( { "http://www.w3.org/1999/02/22-rdf-syntax-ns#type": "http://xmlns.com/foaf/0.1/Person" } );
</pre>
</section>

<section>
<h4>Querying by Property Value</h4>

<p>
The previous query selected all Property Groups of a certain
type, but it did so by indicating that the property <code>rdf:type</code>
should have a specific value. Queries can also specify other
properties. For example, given the following mark-up:
</p>

<pre class="example">
&lt;div typeof="foaf:Person"&gt;
  &lt;span property="foaf:name"&gt;Albert Einstein&lt;/span&gt; -
  &lt;span property="foaf:myersBriggs"&gt;INTP&lt;/span&gt;
  &lt;a rel="foaf:workInfoHomepage" href="http://en.wikipedia.org/wiki/Albert_Einstein"&gt;More...&lt;/span&gt;
&lt;/div&gt;
&lt;div typeof="foaf:Person"&gt;
  &lt;span property="foaf:name"&gt;Mother Teresa&lt;/span&gt; -
  &lt;span property="foaf:myersBriggs"&gt;ISFJ&lt;/span&gt;
  &lt;a rel="foaf:workInfoHomepage" href="http://en.wikipedia.org/wiki/Mother_Teresa"&gt;More...&lt;/span&gt;
&lt;/div&gt;
&lt;div typeof="foaf:Person"&gt;
  &lt;span property="foaf:name"&gt;Marie Curie&lt;/span&gt; - 
  &lt;span property="foaf:myersBriggs"&gt;INTP&lt;/span&gt;
  &lt;a rel="foaf:workInfoHomepage" href="http://en.wikipedia.org/wiki/Marie_Curie"&gt;More...&lt;/span&gt;
&lt;/div&gt;
</pre>

<p>
The following query demonstrates how a developer would select and use
all Property Groups of type <i>Person</i> that also have a Myers Brigg's 
personality type of "INTP" (aka: The Architect):
</p>

<pre class="example">
var architects = query.select( {
  "http://www.w3.org/1999/02/22-rdf-syntax-ns#type": "http://xmlns.com/foaf/0.1/Person",
  "http://xmlns.com/foaf/0.1/myersBriggs": "INTP"
} );

var name = architects[0].get("http://xmlns.com/foaf/0.1/name");
</pre>

<p>
As before, prefix-mappings can also be used:
</p>

<pre class="example">
var architects = query.select( {"rdf:type": "foaf:Person", "foaf:myersBriggs": "INTP"} );

var name = architects[0].get("foaf:name");
</pre>

<p>
Directives to generate the Property Group object based on a template
specified by the developer can also be used. In this case, all of the "INTP"
personality types are gleaned from the page and presented as Property Groups
containing each person's name and blog page:
</p>

<pre class="example">
var architects = query.select( {"rdf:type": "foaf:Person", "foaf:myersBriggs": "INTP"},
                               {"foaf:name": "name", "foaf:workInfoHomepage", "info" } );

var name = architects[0].name;
var infoWebpage = architects[0].info;
</pre>

</section>
</section>

<section>
<h3>Direct Access to the Data Store</h3>

<p>
The RDFa DOM API allows a developer to not only query the Data Store at via 
the Data Query mechanism, it also allows a developer to get to
the underlying data structures that represent the structured data at the
"atomic level".
</p>

<p>
The <code>filter</code> interface is a part of the Data Store and enables a
developer to filter a series of triples out of the Data Store. For example,
to extract all triples about a particular subject, the developer could do
the following:
</p>

<pre class="example">
var names = document.data.store.filter("http://example.org/people#benjamin");
</pre>

<p>
Developers could also combine subject-predicate filters by doing the following:
</p>

<pre class="example">
var names = document.data.store.filter("http://example.org/people#benjamin", "foaf:nick");
</pre>

<p>
The query above would extract all known nicknames for the subject as triples.
</p>

</section>

<section>
<h3>Direct Access to the Parser Stream</h3>

<p>
The <code>iterate</code> interface can be used to process triples in the
document as they are discovered. This interface is most useful for processing 
large amounts of data in low-memory environments.
</p>

<pre class="example">
var iter = document.data.parser.iterate("http://example.org/people#mark");
for(var triple = iter.next(); iter != null; triple = iter.next()) 
{
   // process each triple that is associated with http://example.org/people#mark
}
</pre>

</section>

<section>
<h3>Overriding the Defaults</h3>

<p>
The major modules in the RDFa DOM API are meant to be overridden by developers
in order to extend basic functionality as well as innovate new interfaces for
the RDFa DOM API.
</p>

<section>
<h4>Overriding the Data Store</h4>

<p>
The API is designed such that a developer may override the default data
store provided by the browser by providing their own. This is useful, 
for instance, if the developer wanted to create a permanent site-specific
data store using Local Storage features in the browser, or allowing provenance
information to be stored with each triple.
</p>

<pre class="example">
var mydatastore = new MyCustomDataStore();

document.data.store = mydatastore;
</pre>

</section>

<section>
<h4>Overriding the Data Parser</h4>

<p>
Developers may create and specify different parsers for parsing structured
data from the document that builds upon RDFa, or parses other languages not
related to RDFa. For example, Microformats-specific parsers could be created
to extract structured hCard data and store it in an object that is
compatible with the Data Store interface.
</p>

<pre class="example">
var hcardParser = new MyHCardParser();

document.data.parser = hcardParser;
</pre>

</section>

<section>
<h4>Overriding the Data Query</h4>

<p>
The query mechanism for the API can be overridden to provide different or more
powerful query mechanisms. For example, by replacing the standard query 
mechanism, developers could provide a full SPARQL query mechanism:
</p>

<pre class="example">
var sparqlQuery = new MySparqlEngine();
document.data.query = sparqlQuery;

var books = document.data.query.select("SELECT ?book ?title WHERE { ?book &lt;http://purl.org/dc/elements/1.1/title> ?title . }");
</pre>

</section>
</section>
</section>
</section>


<section class='normative'>
<h1>The Interfaces Specification</h1>

<p>
The following section contains all of the interfaces that developers are 
expected to implement.
</p>

<section>
<h2>The RDF Interfaces</h2>

<p>
RDFa is a syntax for expressing the RDF Data Model [[RDF-CONCEPTS]] in 
Web documents. The <em>RDFa DOM API</em> is designed to extract the RDF Data
Model from Web documents. The following RDF Resources are utilized in this
specification: <em>Plain Literals</em>, <em>Typed Literals</em>, 
<em>IRI References</em> (as defined in [[!IRI]]) and <em>Blank Nodes</em>. The 
interfaces for each of these RDF Resources are detailed in this section. The 
types as exposed by the RDFa DOM API conform to the same data and 
comparison restrictions as specified in the RDF concepts 
specification [[!RDF-CONCEPTS]] and the [[!IRI]] specification.
</p>

<p>
Each RDF interface provides access to both the extracted RDFa value and 
the DOM Node from which the value was extracted. This allows developers
to extract and use RDF triples from a host language and 
also manipulate the DOM based on the associated DOM Node. For example,
an agent could highlight all strings that are marked up as
<code>foaf:name</code> properties in a Web document.
</p>

<p>
The basic RDF Resource types used in the RDFa DOM API are:</p>
<ul>
  <li><a href="#iri-references">IRI Reference</a> &mdash; A reference to a
  resource as defined in International Resource Identifier [[!IRI]]. Example: 
  <code>http://www.w3.org/2001/XMLSchema#string</code>.
  </li>
  <li><a href="#plain-literals">Plain Literal</a> &mdash; A
  string value with optional information about the language of its
  content. Example: <code>"Harry Potter and the Half-Blood
  Prince"@en</code> is a plain literal expressed in the English language.</li>
  <li><a href="#typed-literals">Typed Literal</a> &mdash; A
  typed string value with information about the datatype of its content. 
  Example:
  <code>"7"^^xsd:integer</code> is a typed literal with a value of type 
  <code>xsd:integer</code>.
  </li>
  <li><a href="#blank-nodes">Blank Node</a> &mdash; A blank node is a reference
  to a resource that does not have a corresponding IRI. Examples of Blank Nodes 
  include  <code>_:me</code>, and <code>_:42</code>.</li>
  <li><a href="#rdf-triples">RDF Triple</a> &mdash; Triples are the
  basic data structure utilized by RDF to express logical statements. An RDF 
  triple is a 3-item ordered set consisting of a <em>subject</em>, a 
  <em>predicate</em>, and 
  an <em>object</em>. Example: <code>&lt;http://example.org/hp&gt; 
  rdfs:label "Harry Potter" .</code></li>
</ul>

<p>
An RDFa DOM API implementer MUST provide the basic types as described in
this specification. An implementer may provide additional types and/or a deeper
type or class hierarchy that includes these basic types.</p>

<section class="normative">
<h3>IRI References</h3>
<p>
An IRI Reference in the <em>RDFa DOM API</em> points to a resource and is
further defined in [[!IRI]].</p>

<dl
  title="[Constructor(in DOMString value), 
 Constructor(in DOMString value, in Node origin), 
 Stringifies=value] 
 interface IRI"
  class="idl">
  <dt>readonly attribute DOMString value</dt>
  <dd>The lexical representation of the IRI reference.</dd>

  <dt>readonly attribute Node origin</dt>
  <dd>The node that specifies the IRI's value in the RDFa markup.</dd>

</dl>
</section>
<!-- END s_rdf_IRI-->

<section class="normative">
<h2>RDF Literals</h2>

<p>
An <em>RDF Literal</em> is an RDF Resource that represents
lexical values in RDFa data. The two <em>RDF Literals</em> provided via the
<em>RDFa DOM API</em> are PlainLiterals and TypedLiterals. For a given <em>RDF
Literal</em>, either language or type information can be provided. If the type
is set, the <em>RDF Literal</em> is a <em>Typed
Literal</em>. If a type is not set, it is a <em>Plain Literal</em>.</p>

<dl>
  <dt>PlainLiteral</dt>
  <dd>RDF Literals that may contain language information about the
  given text. The language is specified as a text string as specified
  in [[!BCP47]] 
  (e.g., <code>'en'</code>, <code>'fr'</code>, <code>'de'</code>).</dd>

  <dt>TypedLiteral</dt>
  <dd>RDF Literals that contain type information about the given
  text. The type is always specified in the form of an IRI Reference 
  (e.g., <code>http://www.w3.org/2001/XMLSchema#DateTime</code>).</dd>
</dl>

<section class="normative">
<h4>Plain Literals</h4>

<p>
PlainLiterals have a string value and may specify a language.</p>

<p class="issue">
The RDFa Working Group is considering whether plain literals should express
literal values as UTF-8, or whether the encoding of the source document
should be used instead. This section assumes that the encoding from the source
document should be used.
</p>

<dl
  title="[Constructor(in DOMString value), 
 Constructor(in DOMString value, in DOMString language), 
 Constructor(in DOMString value, in DOMString language, in Node origin), 
 Stringifies=value] 
 interface PlainLiteral"
  class="idl">
  <dt>readonly attribute DOMString value</dt>
  <dd>The lexical value of the literal encoded in the character
  encoding of the source document. The value is extracted from an RDFa document
  using the algorithm defined in the RDFa Core Specification [[!RDFA-CORE]],
  Section 7.5: <a href="http://www.w3.org/TR/rdfa-core/#sequence">Sequence</a>,
  Step 11.
  </dd>

  <dt>readonly attribute DOMString language</dt>
  <dd>A two character language string as defined in  [[!BCP47]], 
  normalized to lowercase.</dd>

  <dt>readonly attribute Node origin</dt>
  <dd>The first node in the DOM tree that is associated with this PlainLiteral.</dd>
</dl>

<section class="informative">
<h5>Example</h5>
<p>
The following example demonstrates a few common use cases of the 
PlainLiteral type.</p>
<pre class='example' data-transform='updateExample'>
<!--
>> var literal = document.data.store.createPlainLiteral('Harry Potter and the Half-Blood Prince', 'en');
>> print(literal.toString());
Harry Potter and the Half-Blood Prince
>> print(literal.value);
Harry Potter and the Half-Blood Prince
>> print(literal.language);
en
-->
</pre>
</section>
<!-- END EXAMPLE -->
</section>
<!-- END s_rdf_plainliteral -->

<section class="normative">
<h4>Typed Literals</h4>
<p>
A TypedLiteral has a string value and a datatype specified as an <a
  href="#iri-references">IRI Reference</a>. TypedLiterals can be converted
into native language datatypes of the implementing programming
language by registering a 
<a href="#typed-literal-converter">Typed Literal Converter</a> as defined later 
in the specification.</p>

<p>
The datatype's IRI reference specifies the datatype of the text
value, e.g., <code>xsd:DataTime</code> or <code>xsd:boolean</code>.</p>

<p>
The RDFa DOM API provides a method to explicitly convert
TypedLiteral values to native datatypes supported by the host programming
language. Developers may write their own <a
  href="#typed-literal-converters">Typed Literal Converters</a> in
order to convert an RDFLiteral into a native language type. The
converters are registered by using the <a
  href="#widl-rdfa-registerTypeConversion">registerTypeConversion()</a>
method. Default TypedLiteral converters MUST be supported by the
RDFa DOM API implementation for the following 
<a href="http://www.w3.org/2001/XMLSchema-datatypes">XML Schema datatypes</a>:
</p>
<ul>
  <li>xsd:string</li>
  <li>xsd:boolean</li>
  <li>xsd:float</li>
  <li>xsd:double</li>
  <li>xsd:boolean</li>
  <li>xsd:integer</li>
  <li>xsd:long</li>
  <li>xsd:date</li>
  <li>xsd:time</li>
  <li>xsd:dateTime</li>
</ul>

<dl
  title="[Constructor(in DOMString value, in IRI type), 
 Constructor(in DOMString value, in IRI type, in Node origin), 
 Stringifies=value] 
 interface TypedLiteral"
  class="idl">
  <dt>readonly attribute DOMString value</dt>
  <dd>The lexical value of the literal encoded in the character
  encoding of the source document. The value is extracted from an RDFa document
  using the algorithm defined in the RDFa Core Specification [[!RDFA-CORE]],
  Section 7.5: <a href="http://www.w3.org/TR/rdfa-core/#sequence">Sequence</a>,
  Step 11.</dd>

  <dt>readonly attribute IRI type</dt>
  <dd>A datatype identified by an IRI reference</dd>

  <dt>readonly attribute Node origin</dt>
  <dd>The first node in the DOM tree that is associated with this
  TypedLiteral.</dd>

  <dt>Any valueOf( )</dt>
  <dd>Returns a native language representation of this literal. The type
  conversion should be performed by translating the value of the literal using 
  the IRI reference of the datatype to the closest native datatype in the 
  programming language.</dd>
</dl>

<section class="informative">
<h5>Example</h5>
<p class="example">The following example demonstrates how a TypedLiteral
representing a date is automatically converted to JavaScript's native 
DateTime object.</p>
<pre class='example' data-transform='updateExample'>
<!--
>> var literal = document.data.store.createTypedLiteral('2010-12-24', "xsd:date");
>> print(literal.toString());
2010-12-24
>> print(literal.value);
2010-12-24
>> print(literal.valueOf());
Fri Dec 24 2010 00:00:00 GMT+0100
-->
</pre>
</section>
<!-- END EXAMPLE -->
</section>
<!-- END s_rdf_typedliteral -->
</section>
<!---END s_rdf_literal-->

<section class="normative">
<h3>Blank Nodes</h3>
<p>
A <code>BlankNode</code> is an <em>RDF resource</em> that does not have a
corresponding IRI reference, as defined in [[!RDF-CONCEPTS]]. The value of a
BlankNode is not required to be the same for identical documents that are
parsed at different times. The purpose of a BlankNode is to ensure that RDF
Resources in the same document can be compared for equivalence by ID.
<p class="issue">The reasoning behind how we stringify BlankNodes should
be explained in more detail.
</p>

<p>
BlankNodes are stringified by concatenating "_:" to BlankNode.value </p>

<dl title="[Constructor, Stringifies] interface BlankNode"
  class="idl">
  <dt>readonly attribute DOMString value</dt>
  <dd>The temporary identifier of the BlankNode. The value MUST NOT be
  relied upon in any way between two separate RDFa processing runs of the 
  same document.</dd>
</dl>

<p class="note">Developers and authors must not assume that the value of a
Blank Node will remain the same between two processing runs. Blank Node values 
are only valid for the most recent processing run on the document. Blank Nodes
values will often be generated differently by different RDFa Processors.</p>

<section class="informative">
<h4>Example</h4>
<p class="example">The following example demonstrates the use of a BlankNode 
in a JavaScript implementation that uses incrementing numbers for the 
identifier.</p>
<pre class='example' data-transform='updateExample'>
<!--
>> var bna = document.data.store.createBlankNode(); // create a new BlankNode A
>> var bnb = document.data.store.createBlankNode(); // create a new BlankNode B
>> print(bna.toString());              // Stringify BlankNode A
_:1
>> print(bna.value);                   //  print value of BlankNode A
1
>> print(bnb.value);                   //  print value of BlankNode B
2
-->
</pre>
</section>
<!-- END EXAMPLE-->
</section>
<!-- END s_rdf_blanknode-->

<section class="normative">
<h3>RDF Triples</h3>
<p>
The RDFTriple interface represents an RDF triple as specified in
[[!RDF-CONCEPTS]]. RDFTriple can be used by referring to properties,
such as <em>subject</em>, <em>predicate</em>, and <em>object</em>. RDFTriple
can also be used by referring to pre-defined indexes. The stringification of 
RDFTriple results in an N-Triples-based representation as defined in [[!N3]].
</p>
<dl
  title="[Constructor(in IRI subject, in IRI predicate, in IRI object),
 Constructor(in IRI subject, in IRI predicate, in PlainLiteral object),
 Constructor(in IRI subject, in IRI predicate, in TypedLiteral object),
 Constructor(in IRI subject, in IRI predicate, in BlankNode object),
 Constructor(in BlankNode subject, in IRI predicate, in IRI object),
 Constructor(in BlankNode subject, in IRI predicate, in PlainLiteral object),
 Constructor(in BlankNode subject, in IRI predicate, in TypedLiteral object),
 Constructor(in BlankNode subject, in IRI predicate, in BlankNode object),
 Stringifies, Null=Null] interface RDFTriple"
  class="idl">

  <dt>const unsigned char LENGTH = 3</dt>
  <dd>The maximum value of an RDF Triple index value.</dd>
  <dt>const unsigned char SUBJECT_INDEX = 0</dt>
  <dd>The index value for the RDF Triple subject.</dd>
  <dt>const unsigned char PREDICATE_INDEX = 1</dt>
  <dd>The index value for the RDF Triple predicate.</dd>
  <dt>const unsigned char OBJECT_INDEX = 2</dt>
  <dd>The index value for the RDF Triple object.</dd>

  <dt>readonly attribute Object subject</dt>
  <dd>The subject associated with the RDFTriple.</dd>
  <dt>readonly attribute Object predicate</dt>
  <dd>The predicate associated with the RDFTriple.</dd>
  <dt>readonly attribute Object object</dt>
  <dd>The object associated with the RDFTriple.</dd>

  <dt>[IndexGetter] Object get( )</dt>

  <dd>Returns the RDFTriple property at the given index.
  <dl class="parameters">
    <dt>unsigned char index</dt>
    <dd>A property index in the range of 0 to 2. The following index values 
    are mapped to the following RDFTriple properties:
    <table>
      <thead>
        <tr>
          <th>Index</th>
          <th>Alias</th>
          <th>Property</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>0</td>
          <td>SUBJECT_INDEX</td>        
          <td>subject</td>
        </tr>
        <tr>
          <td>1</td>
          <td>PREDICATE_INDEX</td>
          <td>predicate</td>
        </tr>
        <tr>
          <td>2</td>
          <td>OBJECT_INDEX</td>
          <td>object</td>
        </tr>
      </tbody>
    </table>
  </dl>
  </dd>

</dl>

<section class="informative">
<h4>Example</h4>
<p>
The following examples demonstrate the basic usage of an RDFTriple object.
The creation of the triple uses the <code>foaf:name</code> CURIE, which
is transformed into an IRI. The example assumes that a mapping has already been 
created for <code>foaf</code>. For more information on creating RDFa DOM 
API mappings, see the section on <a href="#iri-mapping">IRI Mappings</a>.
</p>
<pre class='example' data-transform='updateExample'>
<!--
>> var triple = document.data.store.createTriple('http://www.example.com#foo', 'foaf:name', \
   document.data.store.createPlainLiteral('foo'));    //create a new RDFTriple
>> print(triple.subject);        // print the property subject of the RDFTriple
http://www.example.com#foo
>> print(triple[0]);             // use the index getter to print the subject of the RDFTriple
http://www.example.com#foo
>> print(triple.toString());     // stringify the RDFTriple
<http://www.example.com#foo> <http://xmlns.com/foaf/0.1/name> "foo" .
-->
</pre>
</section>
<!--END  EXAMPLE -->

</section>
<!--END  s_rdf_triple-->
</section>

<section class="normative">
<h2>The Structured Data Interfaces</h2>

<p>
A number of convenience objects and methods are provided by the RDFa DOM
API to help developers manipulate RDF Resources more easily when writing
Web applications.
</p>

<p>
The basic RDF interface types described earlier in this document are
utilized by the following Structured Data Interfaces:</p>
<ul>
  <li><a href="#data-context">Data Context</a> &mdash; 
  A mechanism that greatly reduces the amount of code a developer must write 
  to express IRIs and convert data.
  </li>
  <li><a href="#data-store">Data Store</a> &mdash; An store containing a set
  of RDFTriple objects.</li>
  <li><a href="#data-parser">Data Parser</a> &mdash; An parser that is capable
  of parsing DOM Nodes and placing extracted data into a Data Store.</li>
  <li><a href="#data-iterator">Data Iterator</a> &mdash; An iterator
  capable of incrementally filtering triples discovered via a Data Parser.</li>
  <li><a href="#property-group">Property Group</a> &mdash; An associative
  array of all statements in a document about a single subject.</li>
  <li><a href="#data-query">Data Query</a> &mdash; Provides the capability
  of using a particular language to query and extract values from a Data Store.
  </li>
</ul>

<section class="normative">
<h2>Data Context</h2>
<p>
Processing RDF data involves the frequent use of unwieldy IRI references and
frequent type conversion. The DataContext interface is provided in order to
simplify contextual operations such as shortening IRIs and converting RDF
data into native language datatypes.
</p>

<p>It is assumed that this interface is created and available before a
document is parsed for RDFa data. For example, while operating within a
Browser Context, it is assumed that the following lines of code are executed 
before a developer has access to the RDFa DOM API methods on the 
<code>document</code> object:
</p>

<pre class="example">
document.data.context = new DataContext();
document.data.context.setMapping("rdf", "http://www.w3.org/1999/02/22-rdf-syntax-ns#");
document.data.context.setMapping("xsd", "http://www.w3.org/2001/XMLSchema-datatypes#");
</pre>

<p class="issue">
All of the code that sets up the default type converters for Browser Contexts
that use Javascript should probably be in the code snippet above.
</p>

<p>
The following interface allows IRI mappings to be easily created and
used by Web Developers at run-time. It also allows for conversion of RDF data
into native language datatypes.
</p>

<dl title="interface DataContext" class="idl">

  <dt>void setMapping( in DOMString prefix, in DOMString iri )</dt>
  <dd>Registers a mapping from a prefix to an IRI . The given IRI MUST be a
  full IRI. For example, if a developer 
  wants to specify the <code>foaf</code> IRI mapping, they would call
  <code>setMapping("foaf", "http://xmlns.com/foaf/0.1/")</code>.
  Calling the <code>setMapping()</code> method with a prefix value that does 
  not exist results in the creation of a new mapping. Calling the method
  with a null IRI value will remove the mapping.

  <dl class="parameters">
    <dt>DOMString prefix</dt>
    <dd>The prefix to put into the mapping as the key. (e.g., <code>foaf</code>)</dd>
    <dt>DOMString iri</dt>
    <dd>The IRI reference to place into the mapping as the mapped value of the given prefix.
    (e.g., <code>"http://xmlns.com/foaf/0.1/")</code></dd>
  </dl>
  </dd>
  
  <dt>void registerTypeConversion( )</dt>
  <dd>Registers a type converter from given IRI datatype to a native
  language dataype in the current programming language.

  <dl class="parameters">
    <dt>DOMString iri</dt>
    <dd>A string specifying the IRI datatype. The string MAY be a CURIE. For example: 
       <code>http://www.w3.org/2001/XMLSchema-datatypes#integer</code> or
       <code>xsd:integer</code>.</dd>

    <dt>TypedLiteralConverter converter</dt>
    <dd>A function that converts the TypedLiteral's value into a native language
    datatype in the current programming language.</dd>
  </dl>
  </dd>

</dl>

<section class="normative">
<h3>Automatic Type Conversion</h3>
<p>
TypedLiteralConverter is a callable interface that transforms the
value of a TypedLiteral into a native language type in the current
programming language. The type IRI of the TypedLiteral is used to 
determine the best mapping to the native language type.</p>

<section class="normative">
<h3>Specifing Typed Literal Converters</h3>
<dl title="[Callback] interface TypedLiteralConverter" class="idl">
  <dt>Any convertType ()</dt>
  <dd>Returns the native language value of the passed literal value as a
  language-native type. If the given value cannot be converted, the given
  value must be returned.

  <dl class="parameters">
    <dt>DOMString value</dt>
    <dd>The value to convert that is associated with the RDFTypedLiteral.</dd>
  </dl>
  </dd>
</dl>
</section>

<p>
IRI mappings for all terms in the following vocabularies MUST be included: 
   <a href="http://www.w3.org/1999/02/22-rdf-syntax-ns#">rdf</a> and 
   <a href="http://www.w3.org/2001/XMLSchema-datatypes#">xsd</a>.
</p>

<section>
<h3>Easy IRI Mapping</h3>

<p>
All methods that accept CURIEs as arguments in the RDFa DOM API MUST use 
the algorithm specified in RDFa Core, 
<a href="http://www.w3.org/TR/rdfa-core/#s_curieprocessing">
Section 7.4: CURIE and URI Processing</a> [[!RDFA-CORE]] for
<strong>TERMorCURIEorURI</strong>. The prefix and term mappings are 
provided by the current <code>document.data.context</code> instance.
</p>

<section class="informative">
<h3>Example</h3>
<p>
The following examples demonstrate how mappings are created and used via
the RDFa DOM API.</p>
<pre class='example' data-transform='updateExample'>
// create new IRI mapping
document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/");

// The new IRI mapping is automatically used when CURIEs are expanded to IRIs
var people = document.getItemsByType("foaf:Person");
</pre>

<p>
In the example above, the CURIE "<code>foaf:Person</code>" is expanded
to an IRI with the value "<code>http://xmlns.com/foaf/0.1/Person</code>" in
the <code>getItemsByType</code> method.
</p>

</section>
</section>
<!-- END EXAMPLE-->

<section class="informative">
<h3>Example</h3>
<p>
The following example demonstrates how a developer could register and use
a TypedLiteralConverter.</p>
<pre class='example' data-transform='updateExample'>
<!--
>> document.data.context.registerTypeConversion('xsd:boolean', function(value) {return new Boolean(value);});
>> var literal = document.data.store.createTypedLiteral('1', 'xsd:boolean');
>> print(literal.toString());
1
>> print(literal.value);
1
>> print(literal.valueOf());
true
-->
</pre>
</section>
<!---END EXAMPLE-->
</section>
<!---END s_rdf_typedliteral_converter-->
</section>

<section class="normative">
<h3>Data Store</h3>

<p>
The DataStore is a set of RDFTriple objects. It provides a basic getter as well 
as an indexed getter for retrieving individual items from the store. The
Data Store can be used to create primitive types as well as store collections
of them in the form of RDFTriples.</p>

<p class="issue">The forEach method is not properly defined in WebIDL - need
to get input from the WebApps Working Group on how best to author this
interface.</p>

<dl title="interface DataStore" class="idl">

  <dt>readonly attribute unsigned long size</dt>
  <dd>A non-negative integer that specifies the size, in RDFTriples,
  of the store.</dd>

  <dt>[IndexGetter] Object get(in unsigned long index)</dt>
  <dd>Returns the RDFTriple object at the given index in the list.
  <dl class="parameters">
    <dt>unsigned long index</dt>
    <dd>The index of the RDFTriple in the list to retrieve. The value MUST be
    a positive integer value greater than or equal to zero and less than 
    DataStore::length.</dd>
  </dl>
  </dd>

  <dt>boolean add()</dt>
  <dd>Adds an RDFTriple to the Data Store. Returns True if the RDFTriple was
  added to the store successfully.
  <dl class="parameters">
    <dt>RDFTriple triple</dt>
    <dd>The triple to add to the Data Store.</dd>
  </dl>
  </dd>

  <dt>IRI createIRI()</dt>
  <dd>Creates an IRI given a value and an optional Node.
  <dl class="parameters">
     <dt>DOMString iri</dt>
     <dd>The IRI reference's lexical value.</dd>
     <dt>optional Node node</dt>
     <dd>An optional DOM Node to associate with the IRI.</dd>
  </dl>
  </dd>

  <dt>PlainLiteral createPlainLiteral()</dt>
  <dd>Creates a Plain Literal given a value, an optional language and an 
  optional DOM origin Node.
  <dl class="parameters">
     <dt>DOMString value</dt>
     <dd>The value of the IRI. The value can be either a full IRI or a CURIE.</dd>
     <dt>optional DOMString? language</dt>
     <dd>The language that is associated with the Plain Literal encoded 
     according to the rules outlined in [[BCP47]].</dd>
     <dt>optional Node origin</dt>
     <dd>The DOM Node that should be associated with the Plain Literal</dd>
  </dl>
  </dd>

  <dt>TypedLiteral createTypedLiteral()</dt>
  <dd>Creates a Typed Literal given a value, a type and an optional associated 
  DOM Node.
  
  <dl class="parameters">
     <dt>DOMString value</dt>
     <dd>The value of the Typed Literal.</dd>
     <dt>DOMString type</dt>
     <dd>The IRI type of the Typed Literal. The argument can either be a full 
     IRI or a CURIE.</dd>
     <dt>optional Node origin</dt>
     <dd>The DOM Node to associate with the Typed Literal.</dd>
  </dl>
  </dd>

  <dt>BlankNode createBlankNode()</dt>
  <dd>Creates a Blank Node given an optional name value.
  <dl class="parameters">
     <dt>optional DOMString name</dt>
     <dd>The name of the Blank Node, which will be used when Stringifying
     the Blank Node.</dd>
  </dl>
  </dd>

  <dt>RDFTriple createTriple()</dt>
  <dd>Creates an RDF Triple given a subject, predicate and object. If any 
  incoming value does not match the requirements listed below, a Null value
  MUST be returned by this method.
  <dl class="parameters">
     <dt>Object subject</dt>
     <dd>The subject value of the RDF Triple. 
     The value MUST be either an IRI or a BlankNode.</dd>
     <dt>Object predicate</dt>
     <dd>The predicate value of the RDF Triple.</dd>
     <dt>Object object</dt>
     <dd>The object value of the RDF Triple. The value MUST be an IRI, 
     PlainLiteral, TypedLiteral, or BlankNode.</dd>
  </dl>
  </dd>

  <dt>[Null=Null] DataStore filter()</dt>
  <dd>Returns an DataStore, which consists of zero or more RDFTriple 
  objects.

  <dl class="parameters">

    <dt>Object? subject</dt>
    <dd>The subject filter pattern which is used to filter RDFTriple objects.
    Values can be of type IRI, BlankNode, or Null. If the subject is a
    non-Null value, the RDFTriple MUST NOT be placed in the final output
    Array unless the given subject matches the RDFTriple's subject. 
    If subject is set to Null, the filter MUST NOT reject any triple based 
    on the subject.</dd>

    <dt>optional IRI? predicate</dt>
    <dd>The predicate filter pattern which is used to filter RDFTriple objects.
    Values can be of type IRI or Null. If the predicate is a
    non-Null value, the RDFTriple MUST NOT be placed in the final output
    Array unless the given predicate matches the RDFTriple's predicate. 
    If predicate is set to Null, the filter MUST NOT reject any triple based 
    on the predicate.</dd>

    <dt>optional Object? object</dt>
    <dd>The object filter pattern which is used to filter RDFTriple objects.
    Values can be of type IRI, TypedLiteral, PlainLiteral, BlankNode, or Null. 
    If the object is a non-Null value, the RDFTriple MUST NOT be placed in 
    the final output Array unless the given object matches the 
    RDFTriple's object. If object is set to Null, the filter MUST NOT reject any 
    triple based on object.</dd>

    <dt>optional Node? element</dt>
    <dd>The parent DOM Node where filtering should start. The implementation 
    MUST only consider RDF triples on
    the current DOM Node and its children.</dd>

    <dt>optional RDFTripleFilter filter</dt>
    <dd>A user defined function, returning a true or false value, that 
    determines whether or not an RDFTriple should be added to the final 
    Array.</dd>

  </dl>
  </dd>

  <dt>void clear()</dt>
  <dd>Clears all data from the store.</dd>

  <dt>void forEach(in function callback)</dt>
  <dd>Calls the given callback for each item in the Data Store.
  <dl class="parameters">
    <dt>function callback</dt>
    <dd>A function that takes the following arguments: 
    index, subject, predicate, object. The function is called for each item in
    the Data Store.</dd>
  </dl>
  </dd>

</dl>

<section class="informative">
<h4>Example</h4>
<p>
The following examples demonstrate the three mechanisms that are available
for navigating through a DataStore; index getter-based iteration, 
array index-based iteration, and callback-based/functional iteration.</p>
<pre class='example' data-transform='updateExample'>
<!--
>> var store = document.data.store.filter(); // select all RDF triples from the current Data Store
>> print(store.size);                        // print the number of triples in the Data Store
3
>> for(var i=0; i<store.size; i++) {   // loop through filtered RDF triples
     print(store.get(i));                // print RDF triple by using the explicit get method
     print(store[i]);                    // print RDF triple by using the indexed property method
   }
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foo" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foo" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "bar" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "bar" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foobar" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foobar" .
>> function printObject(index, subject, predicate, object) { print(object) } // specify a callback function
>> store.forEach(printObject);           // call the callback function for each item in the array
foo
bar
foobar
-->
</pre>
</section>
<!--END  EXAMPLE -->

</section>
<!--END s_rdf_triplelist -->

<section class='normative'>
<h3>Data Parser</h3>

<p>
The Data Parser is capable of processing a DOM Node and placing the parsing
results into a Data Store. While this section specifies how one would
parse RDFa data and place it into a Data Store, the interface is also intended 
to support the parsing and storage of various Microformats, eRDF, GRDDL, 
DC-HTML, and Microdata. Web developers that would like to write customer 
parsers may extend this interface.
</p>

<dl title="interface DataParser" class="idl">

  <dt>attribute DataStore store</dt>
  <dd>The DataStore that is associated with the DataParser. The results of
     each parsing run will be placed into the store.</dd>

  <dt>[Null=Null] DataIterator iterate( )</dt>
  <dd>Returns an DataIterator, which is capable of iterating through
  a set of RDF triples, one RDFTriple at a time. The DataIterator is 
  most useful in small memory footprint environments, or in documents that 
  contain a very large number of triples.

  <dl class="parameters">

    <dt>Object? subject</dt>
    <dd>The subject filter pattern which is used to filter RDFTriple objects.
    Values can be of type IRI, BlankNode, or Null. If the subject is a
    non-Null value, the RDFTriple MUST NOT be output via the
    DataIterator unless the given subject matches the RDFTriple's subject. 
    An IRI value MUST be either a full IRI or a CURIE.
    If subject is set to Null, the filter MUST NOT reject any triple based 
    on the subject.</dd>

    <dt>optional DOMString? predicate</dt>
    <dd>The predicate filter pattern which is used to filter RDFTriple objects.
    Values can be of type IRI or Null. If the predicate is a
    non-Null value, the RDFTriple MUST NOT be output via the
    DataIterator unless the given predicate matches the RDFTriple's 
    predicate. An IRI value MUST be either a full IRI or a CURIE.
    If predicate is set to Null, the filter MUST NOT reject any triple based 
    on the predicate.</dd>

    <dt>optional Object? object</dt>
    <dd>The object filter pattern which is used to filter RDFTriple objects.
    Values can be of type IRI, TypedLiteral, PlainLiteral, BlankNode, or Null. 
    If the object is a non-Null value, the RDFTriple MUST NOT be output via
    the DataIterator unless the given object matches the 
    RDFTriple's object. An IRI value MUST be either a full IRI or a CURIE.
    If object is set to Null, the filter MUST NOT reject any triple based on 
    object.</dd>

    <dt>optional Node? element</dt>
    <dd>The parent DOM Node where filtering should start. The implementation 
    MUST only consider RDF Triples on the current DOM Node and its children.
    </dd>

    <dt>optional RDFTripleFilter filter</dt>
    <dd>A user defined function, returning a true or false value, that 
    determines whether or not an RDFTriple should be output via the
    DataIterator.</dd>
  </dl>
  </dd>

  <dt>boolean parse()</dt>
  <dd>Parses starting at the given DOM Element and populates the 
  <code>store</code> with the information that is discovered. If a starting
  element isn't specified, or the value of the starting element is Null, then
  the <code>document</code> object MUST be used as the starting element.
  <dl class="parameters">
     <dt>Element domElement</dt>
     <dd>The DOM Element that should trigger triple generation.</dd>
  </dl>
  <div class="note">Even though a specific DOM Element can be specified to
  start the process of placing RDFTriples into the DataStore, the entire
  document MUST be processed by an RDFa Processor due to context that may
  affect the generation of a set of triples. Specifying the DOM Element
  is useful when a subset of the document data is to be stored in the
  Data Store.</div>
  <div class="issue">There are two ways to approach this mechanism. The
  first is to only parse the sub-tree, ignoring the context of the greater
  document. The second is to parse the entire document, but only store
  triples that are a part of the sub-tree.</div>
  </dd>
  
</dl>
</section>

<section class="normative">
<h3>Data Iterator</h3>

<p>
The DataIterator iterates through a DOM subtree and returns RDFTriples
that match a filter function or triple pattern. A DOM Node can
be specified so that only triples contained in the Node and its children will
be a part of the iteration. The DataIterator is provided in order to 
allow implementers to provide a less memory intensive implementation for 
processing triples in very large documents.
</p>

<p>
A DataIterator is created by calling the 
<code>document.data.parser.iterate()</code> method.
</p>

<dl title="interface DataIterator" class="idl">

  <dt>attribute DataStore store</dt>
  <dd>The DataStore that is associated with the DataIterator.</dd>

  <dt>readonly attribute Node root</dt>
  <dd>The DOM Node that was used as the starting point for extracting 
  RDFTriples.</dd>

  <dt>readonly attribute RDFTripleFilter filter</dt>
  <dd>The RDFTripleFilter is a function that is provided by developers to filter
  RDFTriples in a subtree.</dd>

  <dt>readonly attribute RDFTriple triplePattern</dt>
  <dd>An RDF triple pattern is a set of filter parameters that
  can be passed to an RDFTripleFilter to match particular triple patterns.</dd>

  <dt>RDFTriple next ()</dt>
  <dd>Returns the next RDFTriple object that is found in the DOM subtree or
  NULL if no more RDFTriples match the filtering criteria.</dd>
</dl>

<section class="informative">
<h4>Example</h4>
<p>
The following examples describe the how various filter patterns can be
applied to the DOM via document.data.parser.iterate().</p>
<pre class='example' data-transform='updateExample'>
<!--
>> var iter = document.data.parser.iterate();    // iterate over all RDF triples from current Web document as an DataIterator
>> for(var triple = iter.next(); iter != null; triple = iter.next()) {      // step through all RDF triples
     print(triple);              // print current RDF triple
   }
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foo" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "bar" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foobar" .
>> var iter2 = document.data.parser.iterate("http://www.example.com#foo"); // iterate over triples associated with a single subject
>> var iter3 = document.data.parser.iterate(null, "foaf:name"); // iterate over all triples that contain a foaf:name predicate
-->
</pre>
</section>
<!--END  EXAMPLE -->

</section>
<!--END  s_rdf_tripleiterator -->

<section class="normative">
<h3>Property Group</h3>

<p>
The PropertyGroup interface provides a view on a particular subject contained
in the Data Store. The PropertyGroup aggregates the RDFTriples 
as a single language-native object in order to provide a more natural 
programming primitive for developers.
</p>

<p>
PropertyGroup attributes can be accessed in the following ways in Javascript:
</p>

<pre class="example">
// creates a PropertyGroup for the given subject
var person = document.getItemsBySubject("#bob");

// Access the property group attribute via complete IRI
var name = person.get("http://xmlns.com/foaf/0.1/name");

// Access the property group attribute via CURIE
var name = person.get("foaf:name");
</pre>

<dl title="interface PropertyGroup" class="idl">

  <dt>attribute Element origin</dt>
  <dd>The DOM Element that specified the first type definition for this
  PropertyGroup.</dd>

  <dt>attribute Sequence[IRI] properties</dt>
  <dd>A list of all attributes that are available via this PropertyGroup.</dd>

  <dt>Sequence[any] get(in DOMString predicate)</dt>
  <dd>Returns a sequence of IRIs, BlankNodes, PlainLiterals, and/or 
  TypedLiterals in the projection that have a predicate IRI that is equivalent
  to the given value.

  <dl class="parameters">
    <dt>DOMString predicate</dt>
    <dd>A stringified IRI representing a predicate whose values are to be 
    retrieved from the PropertyGroup. For example, using a predicate of
    <code>http://xmlns.com/foaf/0.1/name</code> will return a sequence of 
    values that represent FOAF names in the PropertyGroup. The given
    predicate MAY also be a CURIE.</dd>
  </dl>
  </dd>

</dl>

<section class="informative">
<h4>Example</h4>
<p>
The following examples demonstrate how to use the PropertyGroup interface.</p>
<pre class='example' data-transform='updateExample'>
<!--
>> document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/");
>> var ivan = document.getItemBySubject("http://www.ivan-herman.net/foaf#me"); // extract information about this subject as an PropertyGroup
>> print(ivan.properties);                  // print all projected property names
http://xmlns.com/foaf/0.1/name, 
http://xmlns.com/foaf/0.1/title, 
http://xmlns.com/foaf/0.1/surname, 
http://xmlns.com/foaf/0.1/givenname, 
http://xmlns.com/foaf/0.1/workInfoHomepage
>> ivan.get("foaf:name");                   // named property values of foaf:name
["Herman Iván", "Ivan Herman"]
>> ivan.get("foaf:title");                  // named property values of foaf:title
["Dr."]
>> ivan.get("foaf:workInfoHomepage");       // named property values of foaf:workInfoHomepage
["http://www.iswsa.org/", "http://www.iw3c2.org", "http://www.w3.org/2001/sw/#activity"]
-->
</pre>
</section>
<!--END  EXAMPLE -->

<section>
<h3>The Origin Pointer</h3>

<p>
<code>document.getItemsByType()</code> returns a list of Property Groups 
that match the query. By default there is always a property called
<code>origin</code> on the Property Group and all of its properties, 
which refers back to an element in the source document.
</p>

<p>
The <code>origin</code> property allows programmers to manipulate
DOM objects based on the embedded metadata that they refer to. For
example, to set a thin blue border on each <i>Person</i>, we could
do this:
</p>

<pre class="example">
var people = document.getItemsByType("foaf:Person");
 
for (var i = 0; i &lt; people.length; i++) {
  people[i].origin.style.border = "1px solid blue";
}
</pre>
</section>

<section>
<h3>Property Group Templates</h3>

<p>
A query can be used to retrieve not only basic Property Groups, but can also 
specify how Property Groups are built by utilizing Property Group Templates.
</p>

<p>
For example, assume our source document contains the following
event, marked up using the Google Rich Snippet Event format
(example taken from the Rich Snippet tutorial, and slightly
modified):
</p>

<pre class="example">
&lt;div vocab="http://rdf.data-vocabulary.org/#" typeof="Event"&gt;
  &lt;a href="http://www.example.com/events/spinaltap" rel="v:url" 
     property="summary"&gt;Spinal Tap&lt;/a&gt;
  &lt;img src="spinal_tap.jpg" rel="v:photo" /&gt;
  &lt;span property="description"&gt;After their highly-publicized search for a new drummer, 
  Spinal Tap kicks off their latest comeback tour with a San Francisco show. &lt;/span&gt;
 
  When:
  &lt;span property="startDate" content="20091015T1900Z"&gt;Oct 15, 7:00PM&lt;/span&gt;&acirc;&euro;&rdquo;
  &lt;span property="endDate" content="20091015T2100Z"&gt;9:00PM&lt;/span&gt;
&lt;/div&gt;
</pre>

<p>
To query for all <i>Event</i> Property Groups we know that we can do this:
</p>

<pre class="example">
var ar = query.select({ "rdf:type": "http://rdf.data-vocabulary.org/#Event" });
</pre>

<p>
However, to build a special PropertyGroup that contains the summary, start 
date and end date, we need only do this:
</p>

<pre class="example">
var events = query.select({ "rdf:type": "http://rdf.data-vocabulary.org/#Event" },
                          {"rdf:type" : "type", "v:summary": "summary", 
                           "v:startDate": "start", "v:endDate": "end"} );
</pre>

<p>
The second parameter is a PropertyGroup Template. Each key-value pair 
specifies an IRI to map to an attribute in the resulting PropertyGroup object.
</p>

<p>
Exposing the embedded data in each Property Group makes it easy
to create an HTML anchor that will allow users to add the event to
their Google Calendar, as follows:
</p>

<pre class="example">
var anchor, button, i, pg;
 
for (i = 0; i &lt; events.length; i++) {
  // Get the Property Group:
  pg = events[i];
 
  // Create the anchor
  anchor = document.createElement("a");
 
  // Point to Google Calendar
  anchor.href = "http://www.google.com/calendar/event?action=TEMPLATE"
    + "&amp;text=" + pg.summary + "&amp;dates=" + pg.start + "/" + pg.end;
 
  // Add the button
  button = document.createElement("img");
  button.src = "http://www.google.com/calendar/images/ext/gc_button6.gif";
  anchor.appendChild(button);
 
  // Add the link and button to the DOM object
  pg.origin.appendChild(anchor);
}
</pre>

<p>
The result will be that the event has an HTML <code>a</code> element
at the end (and any <em>Event</em> on the page will follow this
pattern):
</p>

<pre class="example">
&lt;div vocab="http://rdf.data-vocabulary.org/#" typeof="Event"&gt;
  .
  .
  .
  &lt;a href="http://www.google.com/calendar/event?action=TEMPLATE&amp;text=Spinal+Tap&amp;dates=20091015T1900Z/20091015T2100Z"&gt;
    &lt;img src="http://www.google.com/calendar/images/ext/gc_button6.gif" /&gt;
  &lt;/a&gt;
&lt;/div&gt;
</pre>

<p>
For more detailed information about queries see the Data Query interface.
</p>
</section>

</section>
<!--END s_rdf_tripleprojection-->

<section class="normative">
<h3>Data Query</h3>

<p>
The Data Query interface provides a means to query a Data Store. While this
interface provides a simple mechanism for querying a Data Store for RDFa, it
is expected that developers will implement other query interfaces that 
conform to this Data Query interface for languages like SPARQL or other
Domain Specific Language.
</p>

<dl title="interface DataQuery" class="idl">
  <dt>attribute DataStore store</dt>
  <dd>The DataStore that is associated with the DataQuery.</dd>

  <dt>Sequence[PropertyGroup] select ()</dt>
  <dd>Generates a sequence of Property Groups that matches the given selection 
  criteria.
  <dl class="parameters">
    <dt>Object? query</dt>
    <dd>An associative array containing predicates as keys and objects to match
    as values. If the query is null, every item in the Data Store that the
    query is associated with must returned.</dd>
    <dt>optional Object template</dt>
    <dd>A template describing the attributes to create in each Property Group
    that is returned. The template is an associative array containing
    predicates as keys and attribute names that should be created in the
    returned PropertyGroup as values.</dd>
  </dl>
  </dd>

</dl>

</section>

</section>

<section class='normative'>
<h1>The Document Interface</h1>

<p>
The <em>RDFa DOM API</em> is designed to provide a small, powerful
set of interfaces that a developer may use to retrieve RDF triples 
from a Web document. The core interfaces were described in the previous
two sections. This section focuses on the final RDFa API that most
developers will utilize to generate the objects that are described in the
<a href="#the-rdf-interfaces">RDF Interfaces</a> and 
<a href="#the-rdfa-interfaces">RDFa Interfaces sections</a>. The following
API is provided by this specification:</p>

<ul>
  <li><a href="#document-interface-extensions">Document Interface Extensions</a> 
  &mdash; A set of extensions to the Document interface to help developers
  manage structured data in Web documents.
  </li>
  <li><a href="#document-data">Document Data</a> &mdash; The abstract
  container object for managing structured data in a Document.
  </li>
</ul>

<section>
<h2>Document Interface Extensions</h2>

<p>
The following section describes all of the extensions that are necessary to
enable manipulation of structured data within a Web Document.
</p>

<dl title="interface Document" class="idl">

  <dt>readonly attribute DocumentData data</dt>
  <dd>The DocumentData interface is useful for extracting and storing data
     that is associated with the Document.</dd>

  <dt>boolean hasFeature (in DOMString feature)</dt>
  <dd>Checks to see whether or not the document object has the RDFa DOM API 
  feature.
  
  <dl class="parameters">
    <dt>DOMString feature</dt>
    <dd>The feature string to use when checking to see if the Document
    interface has the RDFa DOM API interfaces. This value should be
    "<code>rdfa 1.1</code>".</dd>
  </dl>
  </dd>

  <dt>PropertyGroupList getItemsByType (in DOMString type)</dt>
  <dd>Retrieves a list of PropertyGroup objects based on their
     <code>rdf:type</code> property.

  <dl class="parameters">
    <dt>DOMString type</dt>
    <dd>A DOMString representing an <code>rdf:type</code> to select against.</dd>
  </dl>
  </dd>
  
  <dt>PropertyGroupList getItemBySubject (in DOMString subject)</dt>
  <dd>Retrieves a PropertyGroup object based on its subject.

  <dl class="parameters">
    <dt>DOMString subject</dt>
    <dd>A DOMString representing an IRI-based subject. The string can either
    be a full IRI or a CURIE. If the string is a CURIE, the DataContext will
    be used to resolve the value.</dd>
  </dl>
  </dd>

  <dt>PropertyGroupList getItemsByProperty (in DOMString property, in DOMString value)</dt>
  <dd>Retrieves a list of PropertyGroup objects based on the values of a
     property.

  <dl class="parameters">
    <dt>DOMString property</dt>
    <dd>A DOMString representing an IRI-based property. The string can either
    be a full IRI or a CURIE. If the string is a CURIE, the DataContext will
    be used to resolve the value.</dd>
    <dt>DOMString value</dt>
    <dd>A DOMString representing the value to match against.</dd>
  </dl>
  </dd>

  <dt>NodeList getElementsByType (in DOMString type)</dt>
  <dd>Retrieves a list of Nodes based on the object type of the
     data that they specify.

  <dl class="parameters">
    <dt>DOMString type</dt>
    <dd>A DOMString representing an <code>rdf:type</code> to select against.</dd>
  </dl>
  </dd>

  <dt>NodeList getElementsBySubject (in DOMString subject)</dt>
  <dd>Retrieves a NodeList consisting of Nodes that have explicitly specified
      the given subject.

  <dl class="parameters">
    <dt>DOMString subject</dt>
    <dd>A DOMString representing an IRI-based subject. The string can either
    be a full IRI or a CURIE. If the string is a CURIE, the DataContext will
    be used to resolve the value.</dd>
  </dl>
  </dd>

  <dt>NodeList getElementsByProperty (in DOMString property, in DOMString value)</dt>
  <dd>Retrieves a list of Nodes objects based on the value of a given property.

  <dl class="parameters">
    <dt>DOMString property</dt>
    <dd>A DOMString representing an IRI-based property. The string can either
    be a full IRI or a CURIE. If the string is a CURIE, the DataContext will
    be used to resolve the value.</dd>
    <dt>DOMString value</dt>
    <dd>A DOMString representing the value to match against.</dd>
  </dl>
  </dd>
</dl>
</section>

<section class='normative'>
<h3>Document Data</h3>

<p>
The DocumentData interface is used to create structured-data related
context, storage, parsing and query objects.
</p>

<dl title="interface DocumentData" class="idl">
  <dt>readonly attribute DataStore store</dt>
  <dd>The default DataStore for the document.</dd>

  <dt>readonly attribute DataContext context</dt>
  <dd>The default DataContext for the document.</dd>

  <dt>readonly attribute DataParser parser</dt>
  <dd>The default DataParser for the document.</dd>

  <dt>readonly attribute DataQuery query</dt>
  <dd>The default DataQuery for the document.</dd>
  
  <dt>DataContext createContext()</dt>
  <dd>Creates a DataContext and returns it.</dd>

  <dt>DataStore createStore(in DOMString type)</dt>
  <dd>Creates a DataStore of the given type and returns it.
     <dl class="parameters">
       <dt>DOMString type</dt>
       <dd>The type of DataStore to create.</dd>
     </dl> 
  </dd>

  <dt>DataParser createParser(in DOMString type, in DataStore store)</dt>
  <dd>Creates a DataParser of the given type and returns it.
     <dl class="parameters">
       <dt>DOMString type</dt>
       <dd>The type of DataParser to create.
          For example: "<code>rdfa</code>".</dd>
       <dt>DataStore store</dt>
       <dd>The DataStore to associate with the DataParser.</dd>
     </dl>
  </dd>

  <dt>DataQuery createQuery(in DataStore store)</dt>
  <dd>Creates a DataQuery for the given store.
     <dl class="parameters">
       <dt>DataStore store</dt>
       <dd>The DataStore to associate with the DataQuery.</dd>
     </dl>
  </dd>
  
</dl>
</section>

<section class='normative'>
<h2>Pattern Filters</h2>

<p>
An important goal of the RDFa DOM API is to help Web developers filter
the set of RDF triples in a document down to only the ones that interest
them. This section covers pattern-based filters. Pattern filters trigger off
of one or more of the subject, predicate, or object properties in RDF 
triples. This section also introduces the interfaces for the other
filter types.</p>

<section class='normative'>
<h3>Function Filters</h3>
<p>
Filter criteria may also be defined by the developer as a filter function.
The <code>RDFTripleFilter</code> is a callable function that determines
whether an RDFTriple should be included in the set of output triples.</p>

<dl title="[Callback, Null=Null] interface RDFTripleFilter" class="idl">
  <dt>boolean match ()</dt>
  <dd>A callable function that returns true if the input RDFTriple
  should be included in the output set, or false if the input RDFTriple should
  be rejected from the output set.
  <dl class="parameters">
    <dt>RDFTriple triple</dt>
    <dd>The triple to test against the filter.</dd>
  </dl>
  </dd>
</dl>
</section>
<!-- END s_rdfadomapi_triple_filter_methods_userdefined -->

<section class='informative'>
<h3>Example</h3>
<p>
The examples below use the following HTML code:
</p> 
<pre class="example"  data-transform='updateExample'>
<!--
<div id="start" about="http://dbpedia.org/resource/Albert_Einstein">

  <span property="foaf:name">Albert Einstein</span>

  <span property="dbp:dateOfBirth" datatype="xsd:date">1879-03-14</span>
  <div rel="dbp:birthPlace" resource="http://dbpedia.org/resource/Germany">
    <span class="hilite"><span property="dbp:conventionalLongName">Federal Republic of Germany</span></span>
  </div>
</div>
-->
</pre>

<p class="example">
The following examples demonstrate the use of document.data.store.filter() and 
document.data.parser.iterate() 
in JavaScript.</p>
<pre class='example' data-transform='updateExample'>
<!--

>> var myFilter = new function(element, subject, predicate, object) {         // create a filter function that filters 
     if(subject.value.search(/http:\/\/xmlns.com\/foaf\/0\.1/) >= 0) {        // triples with predicates in the foaf namespace.
         return true;
     } 
   }
   
// start filtering at element with id=start
>> var store = document.data.store.filter(null, null, null, document.getElementById("start"), myFilter);
>> store.forEach(function (triple) {
      print(triple)
   }
<http://dbpedia.org/resource/Albert_Einstein> <http://xmlns.com/foaf/0.1/name> "Albert Einstein"


// start filtering by iterating at element with id=start
>> var iter = document.data.parser.iterate(null, null, null, document.getElementById("start"), myFilter);          
>> for(var triple=iter.next(); triple != null; triple = iter.next()) {
      print(triple)
   }
<http://dbpedia.org/resource/Albert_Einstein> <http://xmlns.com/foaf/0.1/name> "Albert Einstein"
-->
</pre>
</section>
</section>
<!-- END s_rdfadomapi_triple_filter -->

<section class='normative'>
<h2>DOM Node Filters</h2>

<p class="issue">
This entire section is probably not necessary anymore. We shoul decide if we
need either of these calls. What use cases do they support that are not
already covered by other interfaces in this document?
</p>

<p>
In addition to filtering RDFTriple objects based on triple patterns, the 
<em>RDFa DOM API</em> also provides a mechanism to filter DOM Nodes that contain
certain triple patterns.</p>
<dl title="interface rdfa" class="idl">
  <dt>NodeList getElements()</dt>
  
  <dd>Return a NodeList of DOM nodes that are filtered by their RDFa content. 
  
  <dl class="parameters">

    <dt>[Variadic] Object? subject</dt>
    <dd>The subject filter pattern which is used to filter DOM Nodes.
    Values can be of type IRI, BlankNode, or Null. If the subject is a
    non-Null value, the DOM Node MUST NOT be placed in the final output
    NodeList unless the given subject matches the RDFTriple's subject. 
    If subject is set to Null, the filter MUST NOT reject any triple based 
    on the subject.</dd>

    <dt>IRI? predicate</dt>
    <dd>The predicate filter pattern which is used to filter DOM Nodes.
    Values can be of type IRI or Null. If the predicate is a
    non-Null value, the DOM Node MUST NOT be placed in the final output
    NodeList unless the given predicate matches the RDFTriple's predicate. 
    If predicate is set to Null, the filter MUST NOT reject any triple based 
    on the predicate.</dd>

    <dt>Object? object</dt>
    <dd>The object filter pattern which is used to filter DOM Nodes.
    Values can be of type IRI, TypedLiteral, PlainLiteral, BlankNode, or Null. 
    If the object is a non-Null value, the DOM Node MUST NOT be placed in 
    the final output NodeList unless the given object matches the 
    RDFTriple's object. If object is set to Null, the filter MUST NOT reject any 
    triple based on object.</dd>

    <dt>Node? element</dt>
    <dd>The parent DOM Node where filtering should start. The implementation MUST only consider RDF triples on
    the current DOM Node and its children.</dd>

    <dt>RDFTripleFilter? filter</dt>
    <dd>A user defined function, returning a true or false value, that 
    determines whether or not a DOM Node should be added to the final 
    NodeList.</dd>

  </dl>
  </dd>

  <dt>boolean containsRDFa()</dt>
  <dd>Tests a node and its descendants to see if it contains RDFa matching
  any of the provided filters.
  <dl class="parameters">

    <dt>Node? element</dt>
    <dd>The parent DOM Node where testing should start. Only RDF triples on
    the given DOM Node and its children are considered.</dd>

    <dt>[Variadic] Object? subject</dt>
    <dd>The subject filter pattern which is used to detect RDFTriple objects.
    Values can be of type IRI, BlankNode, or Null. If the subject is a
    non-Null value, the RDFTriple MUST NOT be a match unless the given subject 
    matches the RDFTriple's subject. 
    If subject is set to Null, any RDFTriple MUST result in a match.</dd>

    <dt>IRI? predicate</dt>
    <dd>The predicate filter pattern which is used to detect RDFTriple objects.
    Values can be of type IRI or Null. If the predicate is a
    non-Null value, the RDFTriple MUST NOT be a match unless the given predicate 
    matches the RDFTriple's predicate. If predicate is set to Null, any 
    RDFTriple MUST result in a match.</dd>

    <dt>Object? object</dt>
    <dd>The object filter pattern which is used to detect RDFTriple objects.
    Values can be of type IRI, TypedLiteral, PlainLiteral, BlankNode, or Null. 
    If the object is a non-Null value, the RDFTriple MUST NOT be a match
    unless the given object matches the RDFTriple's object. If object is set 
    to Null, any RDFTriple MUST result in a match.</dd>

    <dt>RDFTripleFilter? filter</dt>
    <dd>A user defined function, returning a true or false value, that 
    determines whether or not an RDFTriple should be considered a match.</dd>
  </dl>
  </dd>
</dl>


<section class="informative">
<h3>Example</h3>

<p>
The examples below refer to the following HTML code:
</p> 
<pre class="example"  data-transform='updateExample'>
<!--
<div id="start" about="http://dbpedia.org/resource/Albert_Einstein">

  <span property="foaf:name">Albert Einstein</span>

  <span property="dbp:dateOfBirth" datatype="xsd:date">1879-03-14</span>
  <div rel="dbp:birthPlace" resource="http://dbpedia.org/resource/Germany">
    <span class="hilite"><span property="dbp:conventionalLongName">Federal Republic of Germany</span></span>
  </div>
</div>
-->
</pre>

<p>
The following examples demonstrate the usage of rdfa.containsRDFa() and 
rdfa.getElements() in JavaScript:
</p> 

<pre class='example' data-transform='updateExample'>
<!--
>> var germany = new IRI("http://dbpedia.org/resource/Germany")
>> print(rdfa.containsRDFa(document.getElementById("start"), null, null, germany)));  // lookup if html contains RDFa about Germany
true
>> var myFilter = new function(element, subject, predicate, object) {         // create a filter function that filter 
     if(subject.value.search(/http:\/\/xmlns.com\/foaf\/0\.1/) >= 0) {        // for triples with predicates in the foaf namespace.
         return true;  
     } 
   }
>> var nodelist = rdfa.getElements(null, null, null, myFilter);       // filter DOM elements for foaf statements 
>> print(nodelist.length); 
1
-->
  </pre>
</section>
<!-- END EXAMPLE -->

</section>
<!-- END s_rdfadomapi_node_filter -->
</section>
<!-- END  s_rdfadomapi -->
</section>


<section>
<h2>The Initialization Process</h2>

<p>
The RDFa DOM API MUST be initialized before the Web developer has access to
any of the methods that are defined in this specification. To initialize the
API environment in a Browser-based environment, an implementor MUST do the 
following:
</p>

<ol>
<li>create a default Store object, which will hold information obtained
from parsing;</li>
<li>create a defaul Parser object, passing it a pointer to a store;</li>
<li>initiate parsing, to extract information from some object --
usually a DOM object -- and place it into the store;</li>
<li>create a default Query object which can be used to interrogate the
information placed in the store;</li>
</ol>

<p>
Some platforms may merge one or more of these steps as a
convenience to developers. For example, a browser that supports
this API may carry out the first four steps when a document loads,
and then expose a Query interface to allow developers to access the
Property Groups. Some approaches to this will be discussed in the
next section, but before we look at those, we'll give a brief
overview of how each of these phases would normally be
accomplished.
</p>

<section>
<h3>Creating the Data Store</h3>

<p>
To create a store the <code>createStore</code> method is called:
</p>

<pre class="example">
document.data.store = document.data.createStore();
</pre>

<p>
The store object created supports the Store interfaces providing
methods to add metadata to the store. These methods are used during
parsing to populate the store but they can also be used directly to
add additional information. Examples of this are shown later.
</p>
</section>

<section>
<h3>Creating the Data Parser</h3>

<p>
Once a store has been created, the implementor should create a default
parser:
</p>

<pre class="example">
document.data.parser = document.data.createParser("rdfa", store);
</pre>

<p>
Note that an implementation may support many types of parser, so
the specific parser required needs to be specified. For example, an
implementation may also support a Microformats hCard parser:
</p>

<pre class="example">
var parser = document.data.createParser("hCard", store);
</pre>

<p>
Implementations may also support different versions of a parser,
for example:
</p>

<pre class="example">
var parser = document.data.createParser("rdfa1.0", store);
var parser = document.data.createParser("rdfa1.1", store);
</pre>

<p class="issue">
Probably should have a URI to identify
parsers rather than a string, since not only are there many
different Microformats, but also, people may end up wanting to add
parsers for RDF/XML, different varieties of JSON, and so on.
However, if we treat the parameter here as a CURIE, then we can
avoid having long strings. If we do that, then the version number
would need to be elided with the language type: "rdfa1.0",
"rdfa1.1", and so on.
</p>
</section>

<section>
<h3>Parsing the DOM</h3>

<p>
Once we have a parser, we can use it to extract information from
sources that contain embedded data. In the following example we
extract data from the <code>Document</code> object:
</p>

<pre class="example">
parser.parse( document );
</pre>

<p>
Since the parser is connected to a store, the Property Groups
obtained from processing the document are now available in the
variable <code>document.data.store</code>.
</p>

<p>
A store can be used more than once for parsing. For example, if
we wanted to apply an hCard Microformat parser to the same
document, and put the extracted data into the same store, we could
do this:
</p>

<pre class="example">
var store = document.data.createStore();
 
document.data.createParser("rdfa", store).parse();
document.data.createParser("hCard", store).parse();
</pre>

<p>
The store will now contain Property Groups from the RDFa
parsing, as well as Property Groups from the hCard parsing.
</p>

<p>
(If the developer wishes to reuse the store but clear it first,
then the <code>Store.clear()</code> method can be used.)
</p>

<p class="issue">Diagram: Show the connection between a Property Group
and the DOM.</p>
</section>

<section>
<h3>Creating the Data Query</h3>

<p>
Query objects are used to interrogate stores and obtain a list
of DOM objects that are linked to Property Groups. Since there are
a number of languages and techniques that can be used to express
queries, we need to specify the type of query object that we'd
like:
</p>

<pre class="example">
var query = document.data.createQuery("rdfa", store);
</pre>
</section>
</section>


<section class="informative">
<h1>Future Discussion</h1>
<p>
The current version of the <em>RDFa DOM API</em> focuses on filtering 
RDF triples. It also provides methods for filtering DOM Nodes that contain 
certain types of RDF triples.
</p>

<p>
The RDFa Working Group is currently discussing whether or not to include the
following advanced functionality: 
</p>
<ul>
<li>An event mechanism for receiving Triple modification notifications, if
changes occur in the DOM.</li>
<li>A mechanism for adding RDFa data into existing DOM content other than
the direct modification of elements to add RDFa attributes.</li>
<li>A mechanism to load and process triples from remote documents.</li>
</ul>

</section>

<section class="appendix">
<h1>Acknowledgements</h1>

<p>
At the time of publication, the members of the RDFa Working Group
were:</p>

<ul>
  <li>Ben Adida, Creative Commons (Co-Chair)</li>
  <li>Benjamin Adrian, German Research Center for Artificial
  Intelligence (DFKI) GmbH</li>
  <li>Mark Birbeck, webBackplane.com (Invited Expert)</li>

  <li>Abhijit Galkward, Rochester Institute of Technology</li>
  <li>Markus Gylling, DAISY Consortium</li>
  <li>Ivan Herman, <abbr title="World Wide Web Consortium">W3C</abbr></li>
  <li>Toby Inkster (Invited Expert)</li>
  <li>Shane McCarron, Applied Testing and Technology, Inc. (Invited
  Expert)</li>
  <li>Knud Möller (DERI Galway at the National University of
  Ireland)</li>
  <li>John O'Donovan, British Broadcasting Corporation</li>
  <li>Steven Pemberton, Centre for Mathematics and Computer Science
  (CWI)</li>

  <li>Jeffrey Sonstein, Rochester Institute of Technology</li>
  <li>Manu Sporny, Digital Bazaar (Co-Chair, Invited Expert)</li>
  <li>Robert Weir, IBM Corporation</li>
</ul>
</section>
<!-- END s_acknowledgements -->

<!--
<h1>IDL Definitions</h1>

<p>
This document contains the Web IDL definitions of the RDFa DOM
API: <a href="rdfa_dom_api.idl">rdfa_dom_api.idl</a></p>
</section>
<section class="appendix informative">
<h1>JavaScript API Interface Example</h1>

<p>
This document contains a Javascript interface implementation for the RDFa 
DOM API:<a href="rdfa_dom_api.js">rdfa_dom_api.js</a></p>
-->

</body>
</html>

